Skip to main content

SchemaConfig Overview

Every schema in MAPS is stored as a SchemaConfig record. It is the canonical representation, regardless of whether the original format is JSON, Avro, Protobuf, CBC, CBOR, XML, CSV, MessagePack, RAW, or Native.

MAPS uses SchemaConfig for:

  • schema registration
  • topic binding
  • transformations
  • statistics
  • selector evaluation
  • schema-to-schema conversion

1. Core Fields​

versionId​

String representing this schema version.

epoch​

Monotonically increasing long used for ordering.

name / title​

Human-readable identifier.

description / documentation​

Short and long-form documentation for UI and API usage.

format​

Schema type:

  • avro
  • cbc
  • cbor
  • csv
  • json
  • msgpack
  • native
  • protobuf
  • raw
  • xml

2. Schema Body​

schema (JsonObject)​

Unified schema model stored as JSON. Used for:

  • Avro
  • CBC (layout as JSON)
  • CBOR
  • CSV
  • JSON
  • MessagePack
  • Native types
  • Protobuf
  • XML

schemaBase64​

Used for binary/external canonical schema:

  • Protobuf .desc
  • CBC compiled layout
  • Any binary IDL

3. Lifecycle Metadata​

createdAt / modifiedAt​

Audit timestamps.

notBefore / expiresAfter​

Validity interval allowing timed schema activation/deprecation.

4. Labels (Metadata)​

matchExpression​

Regex determining which topics the schema applies to.

Example:

/sensors/temperature/.*

JSON-escaped:

"/demo(/[^/]+)+/power-generation/GEN[0-9]+"

uniqueId​

Stable external schema ID.

interface​

Describes the CoAP interface type for .well-known/core discovery.

Used to generate entries such as:

if="sensor"
if="telemetry"
if="config"

This is part of the CoRE Link Format model.

resource​

Describes the CoAP resource type for .well-known/core.

rt="device"
rt="battery"
rt="ship.subsystem.engine-room"
rt="aircraft.telemetry"

MAPS automatically includes this value in link-format discovery responses so CoAP clients can find typed resources.

source​

Where the schema originated:

  • protobuf
  • avro
  • json
  • manual
  • imported
  • iot-nano

comments​

Free-form notes.

5. Other Behaviour​

pack() / packAsBytes()​

Serialize SchemaConfig to JSON or bytes.

toMap()​

Deprecated legacy converter.

coerceNumber()​

Ensures correct numeric Java type (int/long/double).

6. How MAPS Uses SchemaConfig​

  1. Match schema via matchExpression.
  2. Load schema body (JSON or base64).
  3. Produce Typed Event.
  4. Process through filtering, transforms, statistics, conversions.

SchemaConfig is the core of MAPS schema operations.

CBC Representation Example

Below is a realistic CBC serialization of a SchemaConfig:

{
  "cbcFormat": {
    "messageKey": 0,
    "fields": [
      {
        "name": "sensorId",
        "type": "uint",
        "size": 16,
        "optional": false,
        "fixed": true
      },
      {
        "name": "temperatureC",
        "type": "int",
        "size": 12,
        "optional": false,
        "fixed": true
      }
    ]
  },
  "versionId": "2f8b4235-343b-495f-952c-21855cf222e7",
  "description": "Unit test schema for temperature readings",
  "labels": {
    "uniqueId": "cb063e73-e754-4a5b-9a41-2aaeef3a369c",
    "comments": "Unit Tests",
    "resource": "sensor",
    "interface": "Temperature C",
    "source": "tcp://localhost:1883/topic2"
  },
  "format": "cbc",
  "schema": {
    "messageKey": 0,
    "fields": [
      {
        "name": "sensorId",
        "type": "uint",
        "size": 16
      },
      {
        "name": "temperatureC",
        "type": "int",
        "size": 12
      }
    ]
  },
  "notBefore": "2025-11-07T02:05:12.235223Z"
}