Schemas

Raw ids and numbers become a usable UI through schemas. A schema describes how a service should be presented — human-readable names, units, descriptions, enums, value ranges, display formats and callable methods. Schemas are maintained in the backend and not enforced on the device: labels, enums and units can change without touching firmware.

Schemas exist per service identifier, not per device — one schema covers every device exposing that service.

Loading schemas

const response = await client.fetch("GET", "https://<<URL>>/api/v1/schema?depth=1", { accessToken });
const schemas = await response.json();

[
  {
    "serviceIdentifier": "00000000-0000-2001-8003-006d0099ab53",
    "resourceIdentifier": "crn#tenant:Ba9mN3pQ.schema:00000000-0000-2001-8003-006d0099ab53",
    "schema": {
      "serviceIdentifier": "00000000-0000-2001-8003-006d0099ab53",
      "name": "Climate",
      "description": "Room climate sensor",
      "properties": [
        {
          "id": "0x0800",
          "name": "temperature",
          "type": "UINT16",
          "unit": "°C",
          "readonly": true,
          "display": {
            "fields": [ { "key": "v", "render": { "kind": "scale", "factor": 0.1, "decimals": 1 } } ],
            "text": "{{v}} °C"
          }
        },
        {
          "id": "0x0801",
          "name": "mode",
          "type": "UINT8",
          "enum": [
            { "value": "1", "name": "off" },
            { "value": "2", "name": "silent" },
            { "value": "3", "name": "running" }
          ]
        }
      ]
    }
  }
]

Using schemas in your application

Build a local map from (serviceIdentifier, propertyId) to the schema entry and use it to:

• Show temperature instead of 0x0800.
• Render a dropdown with enum names (off, silent, running) instead of a numeric input.
• Show units, respect readonly, group properties by group.
• Render raw values the way the backend intends via the display format specs — a raw 215 renders as 21.5 °C through the scale spec above.

TIP

Property ids in REST responses are canonical hex strings ("0x0800") on both the flake and the schema side — you can match them directly, no decimal/hex conversion needed. The only place decimal ids appear is the websocket event payload.

Methods

A schema can declare methods for its service — name, parameters, success properties, failure codes. Declared methods are callable by name via POST /devices/…/messages/{name}.

Maintaining schemas

Schemas are created and edited over the API — POST /schema creates one per service identifier, PATCH /schema/{serviceIdentifier} merges changes (list entries are matched by id for properties, name for methods; remove: true deletes the matched entry). Full request/response shapes: schema module reference.