@alteriom/mqtt-schema 0.2.1 → 0.3.1

package/schemas/control_response.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/control_response.schema.json",
+  "title": "Control / Command Response v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "command": {"type": "string"},
+    "status": {"type": "string", "enum": ["ok", "error"]},
+    "message": {"type": "string"},
+    "result": {"type": ["object", "array", "string", "number", "boolean", "null"]}
+  },
+  "additionalProperties": true
+}

package/schemas/envelope.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/envelope.schema.json",
+  "title": "Alteriom MQTT Base Envelope v1",
+  "type": "object",
+  "required": ["schema_version", "device_id", "device_type", "timestamp", "firmware_version"],
+  "properties": {
+    "schema_version": {"type": "integer", "const": 1},
+    "device_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"},
+    "device_type": {"type": "string", "enum": ["sensor", "gateway"]},
+    "timestamp": {"type": "string", "format": "date-time"},
+    "firmware_version": {"type": "string", "minLength": 1, "maxLength": 40},
+    "hardware_version": {"type": "string", "maxLength": 80}
+  },
+  "additionalProperties": true
+}

package/schemas/firmware_status.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/firmware_status.schema.json",
+  "title": "Firmware Update Status v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "event": {"type": "string"},
+    "from_version": {"type": "string"},
+    "to_version": {"type": "string"},
+    "status": {"type": "string", "enum": ["pending", "downloading", "flashing", "verifying", "rebooting", "completed", "failed"]},
+    "progress_pct": {"type": "number", "minimum": 0, "maximum": 100},
+    "error": {"type": ["string", "null"]}
+  },
+  "additionalProperties": true
+}

package/schemas/gateway_info.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/gateway_info.schema.json",
+  "title": "Gateway Info v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "properties": {
+    "mac_address": {"type": "string", "pattern": "^[0-9A-Fa-f:]{17}$"},
+    "ip_address": {"type": "string", "format": "ipv4"},
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "max_nodes": {"type": "integer", "minimum": 0},
+        "supports_mesh": {"type": "boolean"},
+        "firmware_update": {"type": "boolean"}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/gateway_metrics.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/gateway_metrics.schema.json",
+  "title": "Gateway Metrics v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["metrics"],
+  "properties": {
+    "metrics": {
+      "type": "object",
+      "required": ["uptime_s"],
+      "properties": {
+        "uptime_s": {"type": "integer", "minimum": 0},
+        "cpu_usage_pct": {"type": "number", "minimum": 0, "maximum": 100},
+        "memory_usage_pct": {"type": "number", "minimum": 0, "maximum": 100},
+        "temperature_c": {"type": "number"},
+        "connected_devices": {"type": "integer", "minimum": 0},
+        "mesh_nodes": {"type": "integer", "minimum": 0},
+        "packet_loss_pct": {"type": "number", "minimum": 0, "maximum": 100},
+        "data_throughput_kbps": {"type": "number", "minimum": 0}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/mqtt_v1_bundle.json

@@ -0,0 +1,14 @@
+{
+  "$comment": "Convenience bundle referencing all v1 schema artifact filenames for tooling discovery.",
+  "version": 1,
+  "schemas": {
+    "envelope": "envelope.schema.json",
+    "sensor_data": "sensor_data.schema.json",
+    "sensor_heartbeat": "sensor_heartbeat.schema.json",
+    "sensor_status": "sensor_status.schema.json",
+    "gateway_info": "gateway_info.schema.json",
+    "gateway_metrics": "gateway_metrics.schema.json",
+    "firmware_status": "firmware_status.schema.json",
+    "control_response": "control_response.schema.json"
+  }
+}

package/schemas/ota/ota-manifest.schema.json

@@ -0,0 +1,187 @@
+{
+  "$id": "https://schemas.alteriom.com/ota/ota-manifest.schema.json",
+  "title": "Alteriom OTA Firmware Manifest",
+  "description": "Schema for Alteriom OTA firmware manifests supporting both rich and minimal variants",
+  "type": "object",
+  "oneOf": [
+    {
+      "title": "Rich Manifest",
+      "description": "Rich manifest format with environment, branch, and manifests object",
+      "type": "object",
+      "properties": {
+        "environment": {
+          "type": "string",
+          "description": "Target environment (e.g., universal-sensor)"
+        },
+        "branch": {
+          "type": "string",
+          "description": "Source control branch the build originated from"
+        },
+        "manifests": {
+          "type": "object",
+          "description": "Build variants keyed by type (dev, prod, etc.)",
+          "patternProperties": {
+            "^[a-z][a-z0-9-]*$": {
+              "$ref": "#/$defs/richEntry"
+            }
+          },
+          "additionalProperties": false,
+          "minProperties": 1
+        }
+      },
+      "required": ["environment", "branch", "manifests"],
+      "additionalProperties": true
+    },
+    {
+      "title": "Minimal Environment Map",
+      "description": "Minimal manifest format as environment -> channels mapping",
+      "type": "object",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "description": "Environment entry with channel mappings",
+          "patternProperties": {
+            "^[a-z][a-z0-9-]*$": {
+              "$ref": "#/$defs/minimalChannel"
+            }
+          },
+          "additionalProperties": false,
+          "minProperties": 1
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 1
+    }
+  ],
+  "$defs": {
+    "richEntry": {
+      "title": "Rich Build Entry",
+      "description": "Rich manifest build entry (dev or prod)",
+      "type": "object",
+      "properties": {
+        "build_type": {
+          "type": "string",
+          "enum": ["dev", "prod"],
+          "description": "Build type identifier"
+        },
+        "file": {
+          "type": "string",
+          "description": "Firmware binary filename"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Total firmware size in bytes"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the full firmware binary (lowercase hex)"
+        },
+        "firmware_version": {
+          "type": "string",
+          "description": "Semantic or build version string"
+        },
+        "built": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO8601 timestamp when built"
+        },
+        "ota_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Absolute or relative URL to fetch the firmware"
+        },
+        "chunk_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Size of each chunk except possibly the last"
+        },
+        "chunks": {
+          "description": "Either structured chunk objects or array of SHA256 strings",
+          "oneOf": [
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/chunkObject"
+              },
+              "description": "Array of structured chunk objects with metadata"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$",
+                "description": "SHA256 hash of chunk (lowercase hex)"
+              },
+              "description": "Array of SHA256 strings for chunks"
+            }
+          ]
+        }
+      },
+      "required": ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"],
+      "additionalProperties": true
+    },
+    "chunkObject": {
+      "title": "OTA Chunk Object",
+      "description": "Structured chunk metadata with offset and size",
+      "type": "object",
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "0-based sequential chunk index"
+        },
+        "offset": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Byte offset within firmware binary"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Chunk size in bytes"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the chunk (lowercase hex)"
+        }
+      },
+      "required": ["index", "offset", "size", "sha256"],
+      "additionalProperties": true
+    },
+    "minimalChannel": {
+      "title": "Minimal Channel Entry",
+      "description": "Minimal manifest channel entry",
+      "type": "object",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Firmware binary filename"
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Total firmware size in bytes"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA256 hash of the firmware binary (lowercase hex)"
+        },
+        "version": {
+          "type": "string",
+          "description": "Firmware version string"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO8601 timestamp"
+        }
+      },
+      "required": ["file", "size", "sha256", "version", "timestamp"],
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/sensor_data.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_data.schema.json",
+  "title": "Sensor Data Message v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["sensors"],
+  "properties": {
+    "sensors": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["value"],
+        "properties": {
+          "value": {"type": ["number", "integer"]},
+          "unit": {"type": "string"},
+          "raw_value": {"type": ["number", "integer"]},
+          "calibrated_value": {"type": ["number", "integer"]},
+          "quality_score": {"type": "number", "minimum": 0, "maximum": 1},
+          "name": {"type": "string"},
+          "location": {"type": "string"},
+          "additional_data": {"type": "object"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "battery_level": {"type": "integer", "minimum": 0, "maximum": 100},
+    "signal_strength": {"type": "integer", "minimum": -200, "maximum": 0},
+    "additional": {"type": "object"}
+  },
+  "additionalProperties": true
+}

package/schemas/sensor_heartbeat.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_heartbeat.schema.json",
+  "title": "Sensor Heartbeat v1",
+  "type": "object",
+  "required": ["schema_version", "device_id", "device_type", "timestamp"],
+  "properties": {
+    "schema_version": {"type": "integer", "const": 1},
+    "device_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"},
+    "device_type": {"type": "string", "enum": ["sensor", "gateway"]},
+    "timestamp": {"type": "string", "format": "date-time"}
+  },
+  "additionalProperties": true
+}

package/schemas/sensor_status.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.alteriom.io/mqtt/v1/sensor_status.schema.json",
+  "title": "Sensor Status v1",
+  "allOf": [{"$ref": "envelope.schema.json"}],
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "status": {"type": "string", "enum": ["online", "offline", "updating", "error"]},
+    "battery_level": {"type": "integer", "minimum": 0, "maximum": 100},
+    "signal_strength": {"type": "integer", "minimum": -200, "maximum": 0}
+  },
+  "additionalProperties": true
+}

package/schemas/validation_rules.md

@@ -0,0 +1,44 @@
+# Validation Rules (Operational Layer)
+
+This file captures dynamic / contextual validation that is OUTSIDE pure structural JSON Schema constraints.
+
+## Timing & Rate
+- Future timestamp drift: reject if > 5s ahead of server reference.
+- Heartbeat interval recommended 30s; backend may rate-limit <10s.
+- Sensor data soft min 30s unless negotiated high-frequency mode.
+
+## Heartbeat Firmware Version Exception
+- Only heartbeat topic may omit `firmware_version` when unchanged.
+- All other topics require the field.
+
+## Forbidden / Drop Conditions
+| Reason | Condition |
+|--------|----------|
+| missing_fields | Required base fields absent (heartbeat firmware exception applied). |
+| invalid_timestamp | Non-ISO 8601 / unparseable timestamp. |
+| deprecated_keys | Usage of forbidden alias keys (f, fw, ver, version, u, up, rssi). |
+| invalid_sensor_entry | Sensor object missing `value` key. |
+| future_drift | Timestamp too far in future (>5s). |
+| out_of_range | battery_level not 0-100 OR quality_score not 0-1. |
+| invalid_numeric | Non-numeric where numeric expected. |
+| spec_violation | Generic fallback after failed internal validation. |
+
+## Sensor Object Semantics
+- `value` REQUIRED.
+- `unit`, `raw_value`, `calibrated_value`, `quality_score`, `name`, `location`, `additional_data` OPTIONAL.
+- If `quality_score` present must be 0.0–1.0 inclusive.
+
+## Metrics Constraints
+- Gateway metrics MUST appear under `metrics` (never at top-level).
+- Required minimal metric: `uptime_s`.
+
+## Firmware Update Status
+- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
+- `progress_pct` (if present) must be 0–100.
+
+## Extensibility
+- Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.
+
+## Versioning
+- Current `schema_version`: 1
+- Additions remain optional; breaking changes introduce new schema set.

package/types/ota-manifest.d.ts

@@ -0,0 +1,63 @@
+// Type definitions for Alteriom OTA Manifest (rich + minimal variants)
+// Generated manually alongside schema at schemas/ota/ota-manifest.schema.json
+
+export interface OtaChunkObject {
+  index: number;        // 0-based sequential index
+  offset: number;       // byte offset within firmware binary
+  size: number;         // chunk size in bytes
+  sha256: string;       // lowercase hex sha256 of the chunk
+}
+
+// Rich manifest build entry (dev or prod)
+export interface OtaRichEntryBase {
+  build_type: 'dev' | 'prod';
+  file: string;              // firmware-dev.bin or firmware-prod.bin
+  size: number;              // total firmware size (bytes)
+  sha256: string;            // full firmware binary sha256
+  firmware_version: string;  // semantic or build version string
+  built: string;             // ISO8601 timestamp
+  ota_url: string;           // absolute or relative fetch URL
+  chunk_size?: number;       // size each chunk except possibly last
+  // Either structured objects OR array of sha256 strings
+  chunks?: OtaChunkObject[] | string[];
+}
+
+export type OtaRichEntry = OtaRichEntryBase;
+
+export interface OtaRichManifest {
+  environment: string;   // e.g. universal-sensor
+  branch: string;        // source control branch build originated from
+  manifests: {
+    dev?: OtaRichEntry;
+    prod?: OtaRichEntry;
+  };
+}
+
+// Minimal variant channel entry
+export interface OtaMinimalChannel {
+  file: string;      // firmware-dev.bin / firmware-prod.bin
+  size: number;      // bytes
+  sha256: string;    // full firmware sha256
+  version: string;   // version string
+  timestamp: string; // ISO8601 build time
+  chunk_size?: number;
+  chunks?: string[]; // hash-only list (no structured offsets)
+}
+
+export interface OtaMinimalEnv {
+  dev?: OtaMinimalChannel;
+  prod?: OtaMinimalChannel;
+}
+
+// Root minimal map: environment -> channels
+export type OtaMinimalManifest = Record<string, OtaMinimalEnv>;
+
+export type OtaManifest = OtaRichManifest | OtaMinimalManifest;
+
+export function isRichManifest(m: OtaManifest): m is OtaRichManifest {
+  return (m as OtaRichManifest).manifests !== undefined && typeof (m as any).environment === 'string';
+}
+
+export function isMinimalManifest(m: OtaManifest): m is OtaMinimalManifest {
+  return !isRichManifest(m);
+}