signage-contracts

Single source of truth for the Digital Signage platform contracts:

• REST: OpenAPI (openapi/admin-api.yaml)
• Device MQTT (AWS IoT Core): AsyncAPI (asyncapi/device-mqtt.yaml)
• Admin WebSocket events: AsyncAPI (asyncapi/admin-ws.yaml)
• JSON Schemas for message validation (schemas/**)
• TypeScript exports (src/**)

MQTT topic conventions

• Commands to device: t/{tenantId}/d/{deviceId}/cmd
• Acks from device: t/{tenantId}/d/{deviceId}/ack
• Telemetry from device: t/{tenantId}/d/{deviceId}/telemetry

Envelope rules (mandatory)

• Every command has commandId (UUID), type, issuedAt, optional expiresAt, optional desiredVersion
• Every ack references commandId and includes status + timestamp
• Telemetry must be lightweight; large payloads go over HTTPS (manifests/assets)

Next steps

• Add CI validation (OpenAPI lint, AsyncAPI lint, JSON Schema validation)
• Add codegen (TS types from JSON Schemas/OpenAPI) using your preferred toolchain