Skip to main content

JSON Schemas

JSON is one of the most widely used data formats in modern systems. MAPS treats JSON as a first-class schema type, providing full validation, typing, transformation, and statistics support.

1. Format Overview​

JSON (JavaScript Object Notation) originated as a subset of JavaScript but quickly became the lingua franca of REST APIs, IoT payloads, logs, dashboards, and most modern messaging.

Common Characteristics​

  • Human-readable
  • Flexible
  • Extremely well-supported in every language
  • Perfect for telemetry, event logs, configs, and REST-style objects

Why Use JSON in MAPS?​

  • Easy to debug
  • Excellent for prototyping and rapid deployment
  • Converts cleanly to most other formats
  • Ideal for sensor and web-based sources

2. SchemaConfig for JSON​

All JSON schemas in MAPS are stored using a SchemaConfig object:

2.1 Required fields for JSON​

  • format → "json"
  • name → human-readable schema name
  • versionId → logical schema version
  • schema → unified JSON schema definition
  • labels.uniqueId → stable schema identifier

2.2 Example JSON SchemaConfig​

{
  "versionId": "3",
  "name": "bme688",
  "format": "json",
  "labels": {
    "matchExpression": "/device/bme688",
    "uniqueId": "bme688.v3",
    "interface": "sensor",
    "resource": "device",
    "source": "manual"
  },
  "schema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "title": "BME688",
      "description": "VOC, Humidity, Pressure and Temperature Module",
      "type": "object",
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "Optional ISO 8601 UTC timestamp (e.g., 2025-05-29T07:28:15.123Z)",
          "readOnly": true
        },
        "temperature": {
          "type": "number",
          "minimum": -40.0,
          "maximum": 85.0,
          "x-precision": 1.0,
          "description": "Unit: °C"
        },
        "humidity": {
          "type": "number",
          "minimum": 10.0,
          "maximum": 90.0,
          "x-precision": 1.0,
          "description": "Unit: %RH"
        },
        "pressure": {
          "type": "number",
          "minimum": 300.0,
          "maximum": 1100.0,
          "x-precision": 1.0,
          "description": "Unit: hPa"
        },
        "gas": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 65535.0,
          "x-precision": 1.0,
          "description": "Unit: Ω"
        },
        "heaterStatus": {
          "type": "string",
          "description": "Heater on or off"
        },
        "gasMode": {
          "type": "string",
          "description": "Current gas mode"
        }
      },
      "required": [
        "temperature",
        "humidity",
        "pressure",
        "gas",
        "heaterStatus",
        "gasMode"
      ],
      "additionalProperties": false
    },
  "schemaBase64": null
}

2.3 Notes​

  • JSON schemas use the standard MAPS unified schema model.
  • schemaBase64 must remain null for JSON formats.

3. Creating and Registering JSON Schemas​

3.1 Defining a JSON Schema​

Define:

  • fields
  • types
  • nested structures
  • arrays

3.2 Registering with MAPS​

  1. POST schema to Schema Repository
  2. Repository validates it
  3. Schema stored with unique ID
  4. Bind schema → topic/context

3.3 Using JSON Schemas in Java​

MAPS:

  • loads schema
  • parses payload into a Typed Event
  • validates types
  • provides type-safe field access
    JsonSchemaConfig config = new JsonSchemaConfig();
    config.setComments("Air Quality Breakout");
    config.setTitle("BME688");
    config.setVersion(3);
    config.setResourceType("sensor");
    config.setUniqueId("BME688.v3");
    config.setInterfaceDescription("Air Quality Breakout");
    config.setSchema(getSchema());
    return config;

4. JSON in the MAPS Pipeline​

JSON → Typed Event is efficient and reliable:

  • Supports nested objects
  • Supports arrays
  • Excellent for selectors
  • Excellent for transformations
  • Ideal for statistics
  • Ideal for format conversion

Common pipelines:

  • JSON → CBOR / MessagePack
  • JSON → Avro / Protobuf

5. Compatibility & Mapping Notes​

Maps cleanly to:​

  • Protobuf
  • Avro
  • CBC
  • CSV - ( no nested objects, dates will become strings)
  • CBOR
  • MessagePack
  • XML

Weak spots:​

  • Binary data becomes base64
  • No enum type
  • Loses precision for very large numbers

6. Warnings & Best Practices​

1. Timestamps must be consistent​

Use ISO-8601 or epoch millis.

2. Numbers are ambiguous in vanilla JSON​

MAPS schema fixes this, but producers must still send proper types.

3. Avoid inconsistent shapes​

Missing or shifting fields cause validation failures.

4. Binary must be base64​

JSON cannot represent byte arrays natively.

5. Deeply nested JSON is CPU-heavy​

For high-volume telemetry, use Avro, Protobuf, or CBC.