Skip to main content

CBOR Schemas

CBOR (Concise Binary Object Representation) is a compact, binary serialisation format designed to encode JSON-like data structures efficiently and unambiguously.

1. Description​

CBOR supports integers, floats, binary data, strings, arrays, maps, tagged types, booleans, and null. MAPS uses CBOR for IoT and low-bandwidth environments due to its compact size and schema-free binary tagging capabilities.

2. Schema Format​

MAPS represents CBOR schemas using JSON Schema inside the schema field of SchemaConfig.

Example Schema​

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "temperature": { "type": "number", "minimum": -40, "maximum": 85 },
    "humidity": { "type": "number", "minimum": 0, "maximum": 100 },
    "pressure": { "type": "number", "minimum": 300, "maximum": 1100 },
    "battery": { "type": "integer", "minimum": 0, "maximum": 100 },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO8601 or CBOR Tag 0 or 1"
    }
  },
  "required": [ "temperature", "humidity", "pressure" ]
}

3. SchemaConfig Example​

{
  "versionId": "1",
  "name": "EnvSensor",
  "description": "Environmental CBOR sensor schema.",
  "labels": {
    "uniqueId": "c46f05de-c3d5-45e9-b194-9c890abb7a11",
    "resource": "sensor",
    "interface": "sensor.env",
    "comments": "Compact binary CBOR sensor payload"
  },
  "format": "cbor",
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "minimum": -40,
        "maximum": 85,
        "x-precision": 1,
        "description": "Unit: °C"
      },
      "humidity": {
        "type": "number",
        "minimum": 0,
        "maximum": 100,
        "x-precision": 1,
        "description": "Unit: %RH"
      },
      "pressure": {
        "type": "number",
        "minimum": 300,
        "maximum": 1100,
        "x-precision": 1,
        "description": "Unit: hPa"
      },
      "battery": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100,
        "description": "Unit: %"
      },
      "timestamp": {
        "type": "string",
        "format": "date-time",
        "description": "CBOR tag 0/1 or ISO8601"
      }
    },
    "required": [
      "temperature",
      "humidity",
      "pressure"
    ]
  }
}

4. Java Usage​

Registering the Schema​

SchemaConfig config = SchemaConfig.builder()
    .name("EnvSensor")
    .format("cbor")
    .schema(schemaJsonObject)
    .build();

schemaRepository.register(config);

Processing CBOR Payloads​

Once registered:

  1. CBOR payload received
  2. Decoded into a TypedEvent
  3. Normalised (timestamps → epoch millis, numbers → canonical types)
  4. Made available for filtering, transformations, statistics, and protocol conversion

MAPS treats CBOR identically to JSON/Avro once decoded.

5. CBOR-Specific Notes​

  • CBOR supports native binary blobs, unlike JSON.
  • CBOR timestamps may use:
    • Tag 0 (ISO8601 string)
    • Tag 1 (epoch seconds)
    • Plain ISO8601 text
  • MAPS normalises timestamps to epoch millis.
  • Big integers are supported and converted to BigInteger.
  • Arrays require explicit items definitions in JSON Schema.
  • CBOR maps maintain field names; schema defines the expected structure.