@alteriom/mqtt-schema 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +149 -60
- package/dist/cjs/schema_data.d.ts +181 -0
- package/dist/cjs/schema_data.js +214 -1
- package/dist/cjs/schemas/ota/ota-manifest.schema.json +187 -0
- package/dist/esm/schema_data.js +213 -0
- package/dist/esm/schemas/ota/ota-manifest.schema.json +187 -0
- package/package.json +10 -1
- package/schemas/control_response.schema.json +15 -0
- package/schemas/envelope.schema.json +16 -0
- package/schemas/firmware_status.schema.json +17 -0
- package/schemas/gateway_info.schema.json +21 -0
- package/schemas/gateway_metrics.schema.json +26 -0
- package/schemas/mqtt_v1_bundle.json +14 -0
- package/schemas/ota/ota-manifest.schema.json +187 -0
- package/schemas/sensor_data.schema.json +33 -0
- package/schemas/sensor_heartbeat.schema.json +14 -0
- package/schemas/sensor_status.schema.json +14 -0
- package/schemas/validation_rules.md +44 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://schemas.alteriom.io/mqtt/v1/gateway_info.schema.json",
|
|
4
|
+
"title": "Gateway Info v1",
|
|
5
|
+
"allOf": [{"$ref": "envelope.schema.json"}],
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"mac_address": {"type": "string", "pattern": "^[0-9A-Fa-f:]{17}$"},
|
|
9
|
+
"ip_address": {"type": "string", "format": "ipv4"},
|
|
10
|
+
"capabilities": {
|
|
11
|
+
"type": "object",
|
|
12
|
+
"properties": {
|
|
13
|
+
"max_nodes": {"type": "integer", "minimum": 0},
|
|
14
|
+
"supports_mesh": {"type": "boolean"},
|
|
15
|
+
"firmware_update": {"type": "boolean"}
|
|
16
|
+
},
|
|
17
|
+
"additionalProperties": true
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"additionalProperties": true
|
|
21
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://schemas.alteriom.io/mqtt/v1/gateway_metrics.schema.json",
|
|
4
|
+
"title": "Gateway Metrics v1",
|
|
5
|
+
"allOf": [{"$ref": "envelope.schema.json"}],
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["metrics"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"metrics": {
|
|
10
|
+
"type": "object",
|
|
11
|
+
"required": ["uptime_s"],
|
|
12
|
+
"properties": {
|
|
13
|
+
"uptime_s": {"type": "integer", "minimum": 0},
|
|
14
|
+
"cpu_usage_pct": {"type": "number", "minimum": 0, "maximum": 100},
|
|
15
|
+
"memory_usage_pct": {"type": "number", "minimum": 0, "maximum": 100},
|
|
16
|
+
"temperature_c": {"type": "number"},
|
|
17
|
+
"connected_devices": {"type": "integer", "minimum": 0},
|
|
18
|
+
"mesh_nodes": {"type": "integer", "minimum": 0},
|
|
19
|
+
"packet_loss_pct": {"type": "number", "minimum": 0, "maximum": 100},
|
|
20
|
+
"data_throughput_kbps": {"type": "number", "minimum": 0}
|
|
21
|
+
},
|
|
22
|
+
"additionalProperties": true
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
"additionalProperties": true
|
|
26
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$comment": "Convenience bundle referencing all v1 schema artifact filenames for tooling discovery.",
|
|
3
|
+
"version": 1,
|
|
4
|
+
"schemas": {
|
|
5
|
+
"envelope": "envelope.schema.json",
|
|
6
|
+
"sensor_data": "sensor_data.schema.json",
|
|
7
|
+
"sensor_heartbeat": "sensor_heartbeat.schema.json",
|
|
8
|
+
"sensor_status": "sensor_status.schema.json",
|
|
9
|
+
"gateway_info": "gateway_info.schema.json",
|
|
10
|
+
"gateway_metrics": "gateway_metrics.schema.json",
|
|
11
|
+
"firmware_status": "firmware_status.schema.json",
|
|
12
|
+
"control_response": "control_response.schema.json"
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$id": "https://schemas.alteriom.com/ota/ota-manifest.schema.json",
|
|
3
|
+
"title": "Alteriom OTA Firmware Manifest",
|
|
4
|
+
"description": "Schema for Alteriom OTA firmware manifests supporting both rich and minimal variants",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"oneOf": [
|
|
7
|
+
{
|
|
8
|
+
"title": "Rich Manifest",
|
|
9
|
+
"description": "Rich manifest format with environment, branch, and manifests object",
|
|
10
|
+
"type": "object",
|
|
11
|
+
"properties": {
|
|
12
|
+
"environment": {
|
|
13
|
+
"type": "string",
|
|
14
|
+
"description": "Target environment (e.g., universal-sensor)"
|
|
15
|
+
},
|
|
16
|
+
"branch": {
|
|
17
|
+
"type": "string",
|
|
18
|
+
"description": "Source control branch the build originated from"
|
|
19
|
+
},
|
|
20
|
+
"manifests": {
|
|
21
|
+
"type": "object",
|
|
22
|
+
"description": "Build variants keyed by type (dev, prod, etc.)",
|
|
23
|
+
"patternProperties": {
|
|
24
|
+
"^[a-z][a-z0-9-]*$": {
|
|
25
|
+
"$ref": "#/$defs/richEntry"
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"additionalProperties": false,
|
|
29
|
+
"minProperties": 1
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"required": ["environment", "branch", "manifests"],
|
|
33
|
+
"additionalProperties": true
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"title": "Minimal Environment Map",
|
|
37
|
+
"description": "Minimal manifest format as environment -> channels mapping",
|
|
38
|
+
"type": "object",
|
|
39
|
+
"patternProperties": {
|
|
40
|
+
"^[a-z][a-z0-9-]*$": {
|
|
41
|
+
"type": "object",
|
|
42
|
+
"description": "Environment entry with channel mappings",
|
|
43
|
+
"patternProperties": {
|
|
44
|
+
"^[a-z][a-z0-9-]*$": {
|
|
45
|
+
"$ref": "#/$defs/minimalChannel"
|
|
46
|
+
}
|
|
47
|
+
},
|
|
48
|
+
"additionalProperties": false,
|
|
49
|
+
"minProperties": 1
|
|
50
|
+
}
|
|
51
|
+
},
|
|
52
|
+
"additionalProperties": false,
|
|
53
|
+
"minProperties": 1
|
|
54
|
+
}
|
|
55
|
+
],
|
|
56
|
+
"$defs": {
|
|
57
|
+
"richEntry": {
|
|
58
|
+
"title": "Rich Build Entry",
|
|
59
|
+
"description": "Rich manifest build entry (dev or prod)",
|
|
60
|
+
"type": "object",
|
|
61
|
+
"properties": {
|
|
62
|
+
"build_type": {
|
|
63
|
+
"type": "string",
|
|
64
|
+
"enum": ["dev", "prod"],
|
|
65
|
+
"description": "Build type identifier"
|
|
66
|
+
},
|
|
67
|
+
"file": {
|
|
68
|
+
"type": "string",
|
|
69
|
+
"description": "Firmware binary filename"
|
|
70
|
+
},
|
|
71
|
+
"size": {
|
|
72
|
+
"type": "integer",
|
|
73
|
+
"minimum": 1,
|
|
74
|
+
"description": "Total firmware size in bytes"
|
|
75
|
+
},
|
|
76
|
+
"sha256": {
|
|
77
|
+
"type": "string",
|
|
78
|
+
"pattern": "^[a-f0-9]{64}$",
|
|
79
|
+
"description": "SHA256 hash of the full firmware binary (lowercase hex)"
|
|
80
|
+
},
|
|
81
|
+
"firmware_version": {
|
|
82
|
+
"type": "string",
|
|
83
|
+
"description": "Semantic or build version string"
|
|
84
|
+
},
|
|
85
|
+
"built": {
|
|
86
|
+
"type": "string",
|
|
87
|
+
"format": "date-time",
|
|
88
|
+
"description": "ISO8601 timestamp when built"
|
|
89
|
+
},
|
|
90
|
+
"ota_url": {
|
|
91
|
+
"type": "string",
|
|
92
|
+
"format": "uri",
|
|
93
|
+
"description": "Absolute or relative URL to fetch the firmware"
|
|
94
|
+
},
|
|
95
|
+
"chunk_size": {
|
|
96
|
+
"type": "integer",
|
|
97
|
+
"minimum": 1,
|
|
98
|
+
"description": "Size of each chunk except possibly the last"
|
|
99
|
+
},
|
|
100
|
+
"chunks": {
|
|
101
|
+
"description": "Either structured chunk objects or array of SHA256 strings",
|
|
102
|
+
"oneOf": [
|
|
103
|
+
{
|
|
104
|
+
"type": "array",
|
|
105
|
+
"items": {
|
|
106
|
+
"$ref": "#/$defs/chunkObject"
|
|
107
|
+
},
|
|
108
|
+
"description": "Array of structured chunk objects with metadata"
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
"type": "array",
|
|
112
|
+
"items": {
|
|
113
|
+
"type": "string",
|
|
114
|
+
"pattern": "^[a-f0-9]{64}$",
|
|
115
|
+
"description": "SHA256 hash of chunk (lowercase hex)"
|
|
116
|
+
},
|
|
117
|
+
"description": "Array of SHA256 strings for chunks"
|
|
118
|
+
}
|
|
119
|
+
]
|
|
120
|
+
}
|
|
121
|
+
},
|
|
122
|
+
"required": ["build_type", "file", "size", "sha256", "firmware_version", "built", "ota_url"],
|
|
123
|
+
"additionalProperties": true
|
|
124
|
+
},
|
|
125
|
+
"chunkObject": {
|
|
126
|
+
"title": "OTA Chunk Object",
|
|
127
|
+
"description": "Structured chunk metadata with offset and size",
|
|
128
|
+
"type": "object",
|
|
129
|
+
"properties": {
|
|
130
|
+
"index": {
|
|
131
|
+
"type": "integer",
|
|
132
|
+
"minimum": 0,
|
|
133
|
+
"description": "0-based sequential chunk index"
|
|
134
|
+
},
|
|
135
|
+
"offset": {
|
|
136
|
+
"type": "integer",
|
|
137
|
+
"minimum": 0,
|
|
138
|
+
"description": "Byte offset within firmware binary"
|
|
139
|
+
},
|
|
140
|
+
"size": {
|
|
141
|
+
"type": "integer",
|
|
142
|
+
"minimum": 1,
|
|
143
|
+
"description": "Chunk size in bytes"
|
|
144
|
+
},
|
|
145
|
+
"sha256": {
|
|
146
|
+
"type": "string",
|
|
147
|
+
"pattern": "^[a-f0-9]{64}$",
|
|
148
|
+
"description": "SHA256 hash of the chunk (lowercase hex)"
|
|
149
|
+
}
|
|
150
|
+
},
|
|
151
|
+
"required": ["index", "offset", "size", "sha256"],
|
|
152
|
+
"additionalProperties": true
|
|
153
|
+
},
|
|
154
|
+
"minimalChannel": {
|
|
155
|
+
"title": "Minimal Channel Entry",
|
|
156
|
+
"description": "Minimal manifest channel entry",
|
|
157
|
+
"type": "object",
|
|
158
|
+
"properties": {
|
|
159
|
+
"file": {
|
|
160
|
+
"type": "string",
|
|
161
|
+
"description": "Firmware binary filename"
|
|
162
|
+
},
|
|
163
|
+
"size": {
|
|
164
|
+
"type": "integer",
|
|
165
|
+
"minimum": 1,
|
|
166
|
+
"description": "Total firmware size in bytes"
|
|
167
|
+
},
|
|
168
|
+
"sha256": {
|
|
169
|
+
"type": "string",
|
|
170
|
+
"pattern": "^[a-f0-9]{64}$",
|
|
171
|
+
"description": "SHA256 hash of the firmware binary (lowercase hex)"
|
|
172
|
+
},
|
|
173
|
+
"version": {
|
|
174
|
+
"type": "string",
|
|
175
|
+
"description": "Firmware version string"
|
|
176
|
+
},
|
|
177
|
+
"timestamp": {
|
|
178
|
+
"type": "string",
|
|
179
|
+
"format": "date-time",
|
|
180
|
+
"description": "ISO8601 timestamp"
|
|
181
|
+
}
|
|
182
|
+
},
|
|
183
|
+
"required": ["file", "size", "sha256", "version", "timestamp"],
|
|
184
|
+
"additionalProperties": true
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://schemas.alteriom.io/mqtt/v1/sensor_data.schema.json",
|
|
4
|
+
"title": "Sensor Data Message v1",
|
|
5
|
+
"allOf": [{"$ref": "envelope.schema.json"}],
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["sensors"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"sensors": {
|
|
10
|
+
"type": "object",
|
|
11
|
+
"minProperties": 1,
|
|
12
|
+
"additionalProperties": {
|
|
13
|
+
"type": "object",
|
|
14
|
+
"required": ["value"],
|
|
15
|
+
"properties": {
|
|
16
|
+
"value": {"type": ["number", "integer"]},
|
|
17
|
+
"unit": {"type": "string"},
|
|
18
|
+
"raw_value": {"type": ["number", "integer"]},
|
|
19
|
+
"calibrated_value": {"type": ["number", "integer"]},
|
|
20
|
+
"quality_score": {"type": "number", "minimum": 0, "maximum": 1},
|
|
21
|
+
"name": {"type": "string"},
|
|
22
|
+
"location": {"type": "string"},
|
|
23
|
+
"additional_data": {"type": "object"}
|
|
24
|
+
},
|
|
25
|
+
"additionalProperties": false
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"battery_level": {"type": "integer", "minimum": 0, "maximum": 100},
|
|
29
|
+
"signal_strength": {"type": "integer", "minimum": -200, "maximum": 0},
|
|
30
|
+
"additional": {"type": "object"}
|
|
31
|
+
},
|
|
32
|
+
"additionalProperties": true
|
|
33
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://schemas.alteriom.io/mqtt/v1/sensor_heartbeat.schema.json",
|
|
4
|
+
"title": "Sensor Heartbeat v1",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["schema_version", "device_id", "device_type", "timestamp"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"schema_version": {"type": "integer", "const": 1},
|
|
9
|
+
"device_id": {"type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"},
|
|
10
|
+
"device_type": {"type": "string", "enum": ["sensor", "gateway"]},
|
|
11
|
+
"timestamp": {"type": "string", "format": "date-time"}
|
|
12
|
+
},
|
|
13
|
+
"additionalProperties": true
|
|
14
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://schemas.alteriom.io/mqtt/v1/sensor_status.schema.json",
|
|
4
|
+
"title": "Sensor Status v1",
|
|
5
|
+
"allOf": [{"$ref": "envelope.schema.json"}],
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["status"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"status": {"type": "string", "enum": ["online", "offline", "updating", "error"]},
|
|
10
|
+
"battery_level": {"type": "integer", "minimum": 0, "maximum": 100},
|
|
11
|
+
"signal_strength": {"type": "integer", "minimum": -200, "maximum": 0}
|
|
12
|
+
},
|
|
13
|
+
"additionalProperties": true
|
|
14
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Validation Rules (Operational Layer)
|
|
2
|
+
|
|
3
|
+
This file captures dynamic / contextual validation that is OUTSIDE pure structural JSON Schema constraints.
|
|
4
|
+
|
|
5
|
+
## Timing & Rate
|
|
6
|
+
- Future timestamp drift: reject if > 5s ahead of server reference.
|
|
7
|
+
- Heartbeat interval recommended 30s; backend may rate-limit <10s.
|
|
8
|
+
- Sensor data soft min 30s unless negotiated high-frequency mode.
|
|
9
|
+
|
|
10
|
+
## Heartbeat Firmware Version Exception
|
|
11
|
+
- Only heartbeat topic may omit `firmware_version` when unchanged.
|
|
12
|
+
- All other topics require the field.
|
|
13
|
+
|
|
14
|
+
## Forbidden / Drop Conditions
|
|
15
|
+
| Reason | Condition |
|
|
16
|
+
|--------|----------|
|
|
17
|
+
| missing_fields | Required base fields absent (heartbeat firmware exception applied). |
|
|
18
|
+
| invalid_timestamp | Non-ISO 8601 / unparseable timestamp. |
|
|
19
|
+
| deprecated_keys | Usage of forbidden alias keys (f, fw, ver, version, u, up, rssi). |
|
|
20
|
+
| invalid_sensor_entry | Sensor object missing `value` key. |
|
|
21
|
+
| future_drift | Timestamp too far in future (>5s). |
|
|
22
|
+
| out_of_range | battery_level not 0-100 OR quality_score not 0-1. |
|
|
23
|
+
| invalid_numeric | Non-numeric where numeric expected. |
|
|
24
|
+
| spec_violation | Generic fallback after failed internal validation. |
|
|
25
|
+
|
|
26
|
+
## Sensor Object Semantics
|
|
27
|
+
- `value` REQUIRED.
|
|
28
|
+
- `unit`, `raw_value`, `calibrated_value`, `quality_score`, `name`, `location`, `additional_data` OPTIONAL.
|
|
29
|
+
- If `quality_score` present must be 0.0–1.0 inclusive.
|
|
30
|
+
|
|
31
|
+
## Metrics Constraints
|
|
32
|
+
- Gateway metrics MUST appear under `metrics` (never at top-level).
|
|
33
|
+
- Required minimal metric: `uptime_s`.
|
|
34
|
+
|
|
35
|
+
## Firmware Update Status
|
|
36
|
+
- `status` must be one of: pending, downloading, flashing, verifying, rebooting, completed, failed.
|
|
37
|
+
- `progress_pct` (if present) must be 0–100.
|
|
38
|
+
|
|
39
|
+
## Extensibility
|
|
40
|
+
- Unknown top-level keys tolerated (future evolution) except if they collide with any deprecated alias or reserved future keys announced in CHANGELOG.
|
|
41
|
+
|
|
42
|
+
## Versioning
|
|
43
|
+
- Current `schema_version`: 1
|
|
44
|
+
- Additions remain optional; breaking changes introduce new schema set.
|