Reference · 8 min
Device profile fields
The full list of lab-device-profile-1 fields: what each one means, its limits and how to fix validation errors.
General rules
A profile is data only. It holds no addresses, passwords, scripts or code. An unknown field is a schema error.
File limits: up to 64 KiB of canonical JSON, no repeated keys, no NaN or Infinity. Write numbers as JSON numbers, not strings. true and false go without quotes. An integer field does not accept 60.0.
Validation has four stages: SCHEMA, SEMANTIC, SAFETY and EXECUTION. Each reports on its own. Tests run only when SCHEMA and SEMANTIC have passed.
The global Lab ceiling: 10 kW, 20 kWh, SOC 10–95%, TTL up to 60 seconds, freshness up to 30 seconds. A profile can only narrow these limits.
Identity and version
| Field | Meaning and limits |
|---|---|
| schema_version | Always "lab-device-profile-1". |
| profile_id | Capital Latin letters, digits and hyphens. Starts with a letter. 3 to 128 characters. |
| profile_version | Version X.Y.Z, optionally with a suffix such as 1.2.0-beta.1. Up to 64 characters. |
| status | DRAFT, VALIDATING, VALIDATED or VALIDATION_FAILED. |
| manufacturer, model | Manufacturer and model. 1 to 128 characters. |
| description | Optional. Up to 2000 characters. |
| asset_type | BATTERY, CONTROLLABLE_LOAD, EV_CHARGER or GENERIC_GENERATOR. Test packs exist only for BATTERY and CONTROLLABLE_LOAD. |
| supported_firmware | Conditions separated by spaces, all must hold: ">=1.0.0 <2.0.0". Operators >=, <=, >, <, =. Up to 256 characters. |
| created_by | Author. 1 to 128 characters. |
| created_at, updated_at | ISO 8601 date and time with a time zone. |
The definition hash leaves out status and updated_at. Empty optional fields are left out too. So a status change does not change the hash.
The Lab tests only reference firmware 1.0.0. If your range does not include it, the report gets the blocker REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGE. Other firmware versions show as UNKNOWN in the report.
Connection
| Field | Meaning and limits |
|---|---|
| connection | SIMULATOR, MQTT or HOME_ASSISTANT. |
| home_assistant_mapping | Required for HOME_ASSISTANT and forbidden for the others. It lists HA entities: active_power, soc, soh, available_charge, available_discharge, grid_power, site_load, online, fault, write_consent, sample_timestamp, write_target, write_unit, write_sign, freshness_seconds. |
The HA mapping holds no token or URL. write_target cannot be the same entity as active_power: the measurement must be independent.
CONTROLLABLE_LOAD over HOME_ASSISTANT is not qualified yet. Such a profile fails validation. Use SIMULATOR or MQTT for loads.
Telemetry
telemetry is a list of 1 to 7 mappings. Each one says how a device value becomes a canonical Lab field.
| Field | Meaning and limits |
|---|---|
| field | Canonical field: asset_active_power_kw, soc_pct, soh_pct, available_charge_power_kw, available_discharge_power_kw, grid_active_power_kw, site_load_kw, baseline_kw, power_floor_kw, power_cap_kw. |
| source_key | The key in the device data. It accepts the same canonical names. |
| unit | W, kW or %. A value in W is divided by 1000. |
| scale | A multiplier, above 0 and at most 1000. Default 1. |
| sign | The integer 1 or -1. Default 1. Flips the sign if the device counts the other way. |
Signs in the Lab: asset power is positive when discharging and negative when charging. Grid power is positive on import and negative on export. Load consumption is negative power.
Required fields for BATTERY: asset_active_power_kw, soc_pct, available_charge_power_kw, available_discharge_power_kw. For CONTROLLABLE_LOAD: asset_active_power_kw, baseline_kw, power_floor_kw, power_cap_kw. A load cannot have SOC, SOH or available charge and discharge power.
Commands
| Field | Meaning and limits |
|---|---|
| types | Exactly ["SET_ACTIVE_POWER"]. |
| writable | Exactly ["asset_active_power_kw"]. |
| target_field | "asset_active_power_kw". |
| protected_configuration_writable | Default false. The value true fails SAFETY. |
Constraints: battery
| Field | Meaning and limits |
|---|---|
| max_charge_kw, max_discharge_kw | Above 0, at most 10. |
| capacity_kwh | Above 0, at most 20. |
| soc_min_pct, soc_max_pct | 10 to 95. The minimum must be below the maximum. |
| max_duration_seconds | 1 to 60. No more than max_ttl_seconds. |
| max_ttl_seconds | 1 to 60. |
| freshness_seconds | 1 to 30. Older data blocks commands. |
| baseline_kw | Optional, -10 to 10, default 0. |
| minimum_on_seconds, minimum_off_seconds | Optional, 0 to 60, default 0. |
Constraints: controllable load
For CONTROLLABLE_LOAD, constraints has a different set of fields. All are required. Powers here are positive consumption amounts in kW.
| Field | Meaning and limits |
|---|---|
| baseline_kw | 0 to 10. Usual consumption without a command. |
| power_floor_kw | 0 to 10. The lowest allowed consumption. |
| power_cap_kw | Above 0, at most 10. The highest allowed consumption. |
| max_duration_seconds, max_ttl_seconds | 1 to 60. Duration no more than TTL. |
| freshness_seconds | 1 to 30. |
| minimum_on_seconds, minimum_off_seconds | 0 to 60. How many seconds the load must stay on or off before it switches. |
power_floor_kw <= baseline_kw <= power_cap_kw must hold. Battery fields such as capacity_kwh or soc_min_pct are forbidden here.
Safety
| Field | Meaning and limits |
|---|---|
| ttl_required, fail_closed | Must be true. |
| restore_after_ttl, restore_on_disconnect, abort_restores | Must be true: restore after TTL, on disconnect and on abort. |
| replay_completed | Must be false. A completed command is never replayed. |
| restore_power_kw | -10 to 10. For a battery, 0. For a load, equal to -baseline_kw. |
| stale_policy, offline_policy | REJECT or IGNORE. Only REJECT passes. |
Flexibility and evidence
| Field | Meaning and limits |
|---|---|
| available_up_kw | 0 to 10. Battery: no more than max_discharge_kw. Load: no more than baseline_kw - power_floor_kw. |
| available_down_kw | 0 to 10. Battery: no more than max_charge_kw. Load: no more than power_cap_kw - baseline_kw. |
| response_time_ms | An integer from 0 to 3000. |
| evidence | A list of all five stages: ACKNOWLEDGED, EXECUTED, MEASURED, RESTORE_EXECUTED, RESTORED. |
Custom test vectors
tests holds up to 32 vectors. They are added to the standard pack. In the report a vector is named custom_<vector_id>. A run has at most 96 tests in total.
| Field | Meaning and limits |
|---|---|
| schema_version | "lab-test-vector-1". |
| vector_id | Lowercase Latin letters, digits and _. Starts with a letter, up to 64 characters. Unique. |
| vector_version | Version X.Y.Z. |
| target_kw | -100 to 100. Beyond ±10 kW the command is rejected, so expect REJECTED. |
| duration_seconds | 1 to 60. |
| ttl_seconds | 0 to 60. The value 0 gives an already expired command. |
| fault | NONE or one fault: INTERNET_DISCONNECT, CONNECTOR_DISCONNECT, TELEMETRY_TIMEOUT, STALE_TIMESTAMP, MALFORMED_TELEMETRY, OUT_OF_RANGE_TELEMETRY, DEVICE_FAULT, METER_UNAVAILABLE, ACK_TIMEOUT, EXECUTION_TIMEOUT, RECONNECT, DUPLICATE_ACK, DELAYED_TELEMETRY, CLOCK_SKEW. |
| expected_status | RESTORED, REJECTED, EXPIRED or UNKNOWN. |
| initial_soc_pct | Battery only, and required there. 10 to 95. Forbidden in a load vector. |
{
"schema_version": "lab-test-vector-1",
"vector_id": "short_discharge",
"vector_version": "1.0.0",
"target_kw": 2,
"duration_seconds": 10,
"ttl_seconds": 30,
"fault": "NONE",
"expected_status": "RESTORED",
"initial_soc_pct": 50
}Example
This is the Lab's reference battery profile. It is for learning and does not describe a real product.
{
"schema_version": "lab-device-profile-1",
"profile_id": "WF-PROFILE-LAB-BATTERY-001",
"profile_version": "0.1.0",
"status": "DRAFT",
"manufacturer": "Wesfin Lab",
"model": "Deterministic reference BESS",
"asset_type": "BATTERY",
"supported_firmware": "1.0.0",
"created_by": "lab-author",
"created_at": "2026-10-20T09:00:00+00:00",
"updated_at": "2026-10-20T09:00:00+00:00",
"connection": "SIMULATOR",
"telemetry": [
{"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
{"field": "soc_pct", "source_key": "soc_pct", "unit": "%"},
{"field": "soh_pct", "source_key": "soh_pct", "unit": "%"},
{"field": "available_charge_power_kw", "source_key": "available_charge_power_kw", "unit": "kW"},
{"field": "available_discharge_power_kw", "source_key": "available_discharge_power_kw", "unit": "kW"},
{"field": "grid_active_power_kw", "source_key": "grid_active_power_kw", "unit": "kW"},
{"field": "site_load_kw", "source_key": "site_load_kw", "unit": "kW"}
],
"commands": {"types": ["SET_ACTIVE_POWER"], "writable": ["asset_active_power_kw"], "target_field": "asset_active_power_kw"},
"constraints": {"max_charge_kw": 10, "max_discharge_kw": 10, "capacity_kwh": 20,
"soc_min_pct": 10, "soc_max_pct": 95, "max_duration_seconds": 60,
"max_ttl_seconds": 60, "freshness_seconds": 30},
"safety": {"ttl_required": true, "fail_closed": true, "restore_after_ttl": true,
"restore_on_disconnect": true, "abort_restores": true, "replay_completed": false,
"restore_power_kw": 0, "stale_policy": "REJECT", "offline_policy": "REJECT"},
"flexibility": {"available_up_kw": 10, "available_down_kw": 10, "response_time_ms": 1000},
"evidence": ["ACKNOWLEDGED", "EXECUTED", "MEASURED", "RESTORE_EXECUTED", "RESTORED"],
"tests": []
}For a load, the type, telemetry, constraints, restore power and flexibility change:
"asset_type": "CONTROLLABLE_LOAD",
"telemetry": [
{"field": "asset_active_power_kw", "source_key": "asset_active_power_kw", "unit": "kW"},
{"field": "baseline_kw", "source_key": "baseline_kw", "unit": "kW"},
{"field": "power_floor_kw", "source_key": "power_floor_kw", "unit": "kW"},
{"field": "power_cap_kw", "source_key": "power_cap_kw", "unit": "kW"}
],
"constraints": {"baseline_kw": 5, "power_floor_kw": 0, "power_cap_kw": 10,
"max_duration_seconds": 60, "max_ttl_seconds": 60, "freshness_seconds": 30,
"minimum_on_seconds": 2, "minimum_off_seconds": 2},
"safety": { ... "restore_power_kw": -5 ... },
"flexibility": {"available_up_kw": 5, "available_down_kw": 5, "response_time_ms": 1000}Validation errors
SCHEMA shows the field path and an error type, such as missing, extra_forbidden, literal_error, string_pattern_mismatch or less_than_equal. Up to 32 errors are shown. A mismatch between asset type and constraints or vectors also fails here, with the type value_error.
| Code | What to fix |
|---|---|
| INVALID_PROFILE_DATA | The file does not parse as JSON, is over 64 KiB, has a repeated key or NaN. Fix the JSON itself. |
| FIRMWARE_RANGE_EMPTY | No version satisfies all supported_firmware conditions. Widen the range. |
| HOME_ASSISTANT_MAPPING_REQUIRED | Add home_assistant_mapping or change connection. |
| HOME_ASSISTANT_MAPPING_CONNECTOR_MISMATCH | Remove home_assistant_mapping: it is for HOME_ASSISTANT only. |
| DUPLICATE_TELEMETRY_MAPPING | Each field and each source_key may appear only once. |
| SAFETY_TELEMETRY_MISSING | Add the required telemetry fields for your asset type. |
| LOAD_BATTERY_TELEMETRY_FORBIDDEN | Remove soc_pct, soh_pct and available charge and discharge power from a load. |
| LOAD_HOME_ASSISTANT_NOT_QUALIFIED | Choose SIMULATOR or MQTT for a load. |
| MAPPING_DIMENSION_MISMATCH | A percentage maps only to a percentage, power only to power. |
| PERCENT_MAPPING_INVALID | For _pct fields: unit "%", scale 1, sign 1. |
| POWER_MAPPING_UNIT_INVALID | For power fields, unit must be W or kW. |
| CONSTRAINT_ORDER_INVALID | Check: soc_min_pct < soc_max_pct, duration <= TTL, power_floor_kw <= baseline_kw <= power_cap_kw. |
| FLEXIBILITY_EXCEEDS_DEVICE_LIMIT | Reduce available_up_kw or available_down_kw to the device limits. |
| DUPLICATE_TEST_VECTOR | Give each vector its own vector_id. |
| ttl_required, fail_closed, restore_after_ttl, restore_on_disconnect, abort_restores | SAFETY names the field that is not true. Set it to true. |
| UNSAFE_RECOVERY_POLICY | replay_completed false, both policies REJECT, restore_power_kw 0 for a battery or -baseline_kw for a load. |
| PROTECTED_CONFIGURATION_WRITE | Set protected_configuration_writable to false. |
| DISTINCT_EVIDENCE_REQUIRED | List all five stages in evidence. |
| ASSET_TYPE_PACK_NOT_QUALIFIED | EV_CHARGER and GENERIC_GENERATOR have no test pack yet. The profile cannot become VALIDATED. |
| REFERENCE_FIRMWARE_OUTSIDE_DECLARED_RANGE | Include 1.0.0 in supported_firmware. |
If a test fails in EXECUTION, the test name becomes a blocker. Open it in the report: it shows the inputs, the expectation, the observation and the reason.