Coldwave Documentation

Appearance

Schema Module – Application Guide ​

This guide explains how application developers can use the Schema module of the Coldwave Backend. It focuses on how to:

  • Turn raw device properties into human-friendly fields
  • Drive forms, dashboards and editors from schema definitions
  • Use schema names safely in URLs, expressions and clients
  • Handle schema changes over time

It assumes you understand devices, services and properties and have read the Frontend State Model chapter.

1. Why schemas exist ​

Devices expose raw properties as numeric identifiers with backend types (UINT16, FLOAT, BOOL, …). Without additional metadata, your UI would show fields like “8192 (FLOAT)”.

The Schema module provides:

  • Human-readable names (temperature, mode)
  • Descriptions and units
  • Enum lists
  • Read/write/action flags
  • Groups for UI sections
  • Hints and optional translations

Firmware only knows IDs.
Schemas provide everything needed for UI/UX and application logic.

Schemas can be changed without firmware updates as long as the property ID mapping remains stable.

2. Schema structure in practice ​

Primary endpoint:

http
GET /api/v1/schemas?depth=1

Example response:

jsonc
[
  {
    "serviceIdentifier": "00000000-0000-0000-0000-000000000000",
    "schema": {
      "name": "Example Service",
      "description": "Schema for an example",
      "properties": {
        "0x2000": {
          "name": "mode",
          "description": "Operating mode",
          "type": "uint8",
          "enum": {
            "1": { "name": "off" },
            "2": { "name": "silent" },
            "3": { "name": "running" }
          },
          "readonly": false,
          "actionable": true,
          "group": "General",
          "hint": "Do not change while in maintenance."
        },
        "0x2001": {
          "name": "temperature",
          "description": "Measured temperature",
          "type": "float",
          "unit": "°C",
          "readonly": true,
          "group": "Measurements"
        }
      }
    }
  }
]

2.1 Identifiers ​

  • Property keys are hex ("0x2001")
  • Convert to numeric IDs internally
  • Combine hex + type → typed IDs (0x2001.FLOAT)

2.2 Common property fields ​

  • name — canonical label used in URLs and expressions
  • description — tooltip/help
  • type — backend datatype
  • unit — UI unit
  • readonly — disable writes
  • actionable — treat as action
  • enum — discrete options
  • group, hint — grouping & guidance

3. Fetching and caching schemas ​

Schemas are stable → cache them.

3.1 Bootstrapping sequence ​

http
GET /api/v1/schemas?depth=1&lang=en

Convert response into internal structures:

ts
interface PropertySchema {
  id: number;
  name: string;
  description?: string;
  type: string;
  unit?: string;
  readonly?: boolean;
  actionable?: boolean;
  enum?: Record<string,{name:string;description?:string}>;
  group?: string;
  hint?: string;
}

Refresh schemas:

  • At login
  • On WebSocket schema updates
  • On backend version changes

3.2 Translations ​

Use lang=<locale> for multi-language UIs.

Keep canonical property names stable → translate only labels/descriptions.

4. Building UIs from schemas ​

Schemas enable dynamic UIs without hard-coding property lists.

4.1 Generic property renderer ​

Merge live values + schema:

ts
interface UiProperty {
  id: number;
  key: string;
  label: string;
  unit?: string;
  type: string;
  value: unknown;
  readOnly: boolean;
  enumOptions?: { value: string; label: string }[];
  group?: string;
  hint?: string;
}

Render using:

  • bool → toggle
  • enum → dropdown
  • numeric → input/slider
  • readonly → display only

4.2 Forms / config editors ​

  • Map schema groups → form sections
  • Map types → widgets
  • Use enum metadata
  • Add hints as inline help

4.3 Hiding advanced properties ​

Approaches:

  • Dedicated groups (“Diagnostics”)
  • Naming conventions (_internal)
  • Extra flags in your schema editor

5. Schema names in URLs and expressions ​

Many backend endpoints accept schema names:

  • Open property:
    /api/v1/devices/:dev/services/:svc/openProperty/:property
  • Streams:
    json
    { "property": "currentFloor" }
  • Alarms:
    json
    { "property": "ride-speed" }

⚠ Important caveat ​

If you rename properties in the schema, URLs using the old names break.

Recommended strategy:

  • Use schema names in UI
  • Use typed IDs internally
  • For long-lived configs (alarm expressions, integrations): prefer typed IDs

6. Safe schema changes ​

6.1 Adding properties ​

Safe. Generic UIs pick them up automatically.

6.2 Renaming properties ​

Risky — breaks URLs and configs. Prefer adjusting labels/description instead of renaming name.

6.3 Removing properties ​

Only if firmware removes them. UI should degrade gracefully.

6.4 Changing types or enums ​

Impacts validation and UI widgets. Treat as API changes.

7. Schema WebSocket events ​

Backends may emit:

  • SCHEMA_ADD
  • SCHEMA_UPDATE
  • SCHEMA_DELETE

Handle them by re-fetching /schemas?depth=1.

Schemas change rarely, so re-fetch on demand or when users reload.

8. Permissions ​

Common access model:

  • Viewers/Operators → read-only
  • Admin/OEM → create/update/delete

9. Summary ​

  • Schema module transforms raw properties into a structured, human-friendly model.
  • Ideal for dynamic UIs: lists, forms, editors, dashboards.
  • Cache schemas, merge with live Service data.
  • Use schema names for UI; use typed IDs for stable integrations.
  • Treat schema changes like API changes: add freely, rename rarely, remove carefully.

With robust schema integration, most of your UI becomes reusable across device types and deployments.