Message Structure

3. Message Structure

Top-Level Format (JSON Messages)

All messages, whether sent by sensors, clients, or the backend, follow a consistent top-level JSON structure. This enables schema validation, permission enforcement, and uniform processing across the system.

Required Top-Level Fields

Field	Type	Description
`MessageTypeId`	string	Identifies the type and purpose of the message. Used for routing, schema validation, and permission checks.
`DeviceId`	string	The unique identifier of the originating or target device. Verified during authentication and routing.
`Timestamp`	string	ISO 8601 timestamp marking when the message was created. Must be in UTC.
`Version`	string	Declares the sender’s API protocol version (e.g., "1.0").
`Payload`	object	The message-specific content. Required for text messages, used as metadata container in binary messages.

Example JSON Message

{
  "MessageTypeId": "OSS_STATUS_MESSAGE",
  "DeviceId": "423095324234235",
  "Timestamp": "2025-08-04T14:00:00Z",
  "Version": "1.0",
  "Payload": {
    "status": "ok",
    "uptime": 123456.78,
    "temperature": 45.2
  }
}

Binary Message Framing

Messages that contain image data or other binary payloads follow a framing format that includes a JSON header and a binary body.

Framing Structure

4-byte big-endian unsigned integer — Total payload length in bytes (header + table + binary data + checksum)
4-byte big-endian unsigned integer — Length of the JSON header in bytes
UTF-8 encoded JSON header — Follows the same top-level format as standard messages, including Payload metadata
4-byte big-endian unsigned integer — Number of JPEG XL images in this message
Image length table — An array of 4-byte big-endian unsigned integers, one per image, each indicating the image’s byte length
Binary payload — One or more JPEG XL images compressed near-losslessly, concatenated
4-byte big-endian CRC32 checksum — Covers the entire message from the beginning through the last byte of image data

This structure ensures the receiving system can:

Extract and validate the JSON header before processing the binary data
Enforce permissions and schema checks prior to decoding large or sensitive payloads
Validate payload integrity before further decoding using the checksum

Example Binary Message (Conceptual)

[0x00 0x00 0x10 0x00]       → 4-byte total payload length (4096 bytes)
[0x00 0x00 0x02 0x4A]       → 4-byte JSON header length (586 bytes)
{ UTF-8 JSON Header }        → Includes MessageTypeId, DeviceId, Payload with image metadata
[0x00 0x00 0x00 0x03]       → 4-byte image count (3 images)
[0x00 0x00 0x12 0x34]       → Image 1 length (4660 bytes)
[0x00 0x00 0x23 0x45]       → Image 2 length (9029 bytes)
[0x00 0x00 0x34 0x56]       → Image 3 length (13398 bytes)
[...binary image data...]    → JPEG XL binary image data, back-to-back
[0xDE 0xAD 0xBE 0xEF]       → 4-byte CRC32 checksum over entire preceding message

Notes

All messages, binary or not, must include a valid and authorized MessageTypeId.
JSON schemas are validated before any permission or constraint checks.
For binary messages, only the JSON header is schema-validated.
If present, alarms in the JSON header's Payload are treated as primary message content and must conform to their expected schema.
If no alarm-relevant detections occurred, the alarmRegions field must be omitted.
Timestamp must be in UTC and conform to ISO 8601 format.

Message Structure

On this page