MIOT Metrics Schema

The miot.metrics@1.0 schema defines the canonical JSON structure for metric payloads sent to ModularIoT.

Schema Version

Current version: 1.0

Always include schema_version in your payloads to ensure correct processing.

Payload Structure


{
  "schema_version": "1.0",
  "device_id": "obd-reader-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "metrics": [
    { "key": "engine.rpm", "value": 2500 },
    { "key": "engine.coolant_temp", "value": 85 },
    { "key": "vehicle.speed", "value": 72 },
    { "key": "fuel.level", "value": 65 }
  ]
}

Required Fields

Field	Type	Description
`schema_version`	string	Must be `"1.0"`
`device_id`	string	Unique device identifier (1-255 chars)
`timestamp`	string	ISO 8601 timestamp with timezone
`metrics`	array	At least one metric required

Metric Object

Each metric in the metrics array:

Field	Type	Required	Description
`key`	string	Yes	Canonical metric key
`value`	any	Yes	Measurement value
`timestamp`	string	No	Per-metric timestamp (overrides root)

Supported Value Types

Type	Example	Use Case
number	`72.5`	Most metrics
integer	`2500`	Counts, RPM
boolean	`true`	States (idle, brake)
string	`"P0301"`	Identifiers, VIN
array	`["P0301", "P0420"]`	DTC codes

Optional Fields

Field	Type	Description
`asset_id`	string	Associated asset (if known)
`sequence`	integer	Message sequence for ordering
`batch_id`	string	Batch identifier for grouping

Batching Multiple Timestamps

For buffered data with different timestamps, use per-metric timestamps:


{
  "schema_version": "1.0",
  "device_id": "tracker-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "metrics": [
    { "key": "vehicle.speed", "value": 60, "timestamp": "2024-01-15T10:29:55Z" },
    { "key": "vehicle.speed", "value": 65, "timestamp": "2024-01-15T10:29:56Z" },
    { "key": "vehicle.speed", "value": 68, "timestamp": "2024-01-15T10:29:57Z" },
    { "key": "vehicle.speed", "value": 70, "timestamp": "2024-01-15T10:29:58Z" },
    { "key": "vehicle.speed", "value": 72, "timestamp": "2024-01-15T10:29:59Z" }
  ]
}

JSON Schema (Formal)


{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://modulariot.io/schemas/miot.metrics@1.0",
  "type": "object",
  "required": ["schema_version", "device_id", "timestamp", "metrics"],
  "properties": {
    "schema_version": { "const": "1.0" },
    "device_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "metrics": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["key", "value"],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
          },
          "value": {
            "oneOf": [
              { "type": "number" },
              { "type": "string" },
              { "type": "boolean" },
              { "type": "array" }
            ]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "asset_id": { "type": "string" },
    "sequence": { "type": "integer", "minimum": 0 }
  }
}

Common Mistakes

Mistake	Problem	Fix
Missing `schema_version`	Rejected	Add `"schema_version": "1.0"`
Timestamp without timezone	Ambiguous	Use `Z` or `+00:00` suffix
Empty `metrics` array	Invalid	Include at least one metric
Unknown key without `custom.`	Rejected	Use `custom.` prefix for custom metrics

Full Specification

For complete schema details including all validation rules:

→ Reference > Telemetry Schemas > miot.metrics@1.0