Validation Rules

ModularIoT validates every metric payload at ingestion time. Understanding these rules helps you build drivers that produce clean, accepted data.

Validation Pipeline

Incoming payloads pass through multiple validation stages:

Payload → Schema Validation → Key Validation → Type Validation → Bounds Check → Accept
              ↓                    ↓                 ↓                ↓
           Reject             Reject            Reject           Reject

Each stage can reject the payload with a specific error code. The pipeline stops at the first failure.

Schema Validation

Every payload must conform to the miot.metrics@1.0 schema:

Key Validation

Metric keys must be either canonical or extension keys.

Canonical Keys

Keys must exactly match a registered canonical key:

✓ engine.rpm
✓ vehicle.speed
✓ fuel.level

✗ Engine.RPM       (case mismatch)
✗ engineRpm        (wrong format)
✗ engine_rpm       (underscore instead of dot)

Extension Keys (Custom Metrics)

For vendor-specific metrics, use the x. prefix:

✓ x.vendor.custom_metric
✓ x.teltonika.din1
✓ x.queclink.report_type

✗ custom.vendor.metric    (wrong prefix)
✗ vendor.custom           (no prefix)

Extension keys bypass type and bounds validation but are still logged.

Unknown Key Behavior

Unknown keys (not canonical and not x. prefixed) are rejected by default:

Type Validation

Each canonical key specifies an expected value type:

Type mismatches cause rejection:

// ✗ REJECTED: engine.rpm expects NUMBER, got STRING
{ "key": "engine.rpm", "value": "2500" }
 
// ✓ ACCEPTED
{ "key": "engine.rpm", "value": 2500 }

Bounds Validation

Numeric metrics have defined valid ranges. Values outside these bounds are rejected.

Powertrain Bounds

Fuel Bounds

Motion Bounds

Emissions Bounds

Electrical Bounds

Timestamp Validation

Timestamps prevent stale or future data from polluting the pipeline.

Valid Timestamps

✓ 2024-01-15T10:30:00Z
✓ 2024-01-15T10:30:00+00:00
✓ 2024-01-15T05:30:00-05:00

✗ 2024-01-15T10:30:00      (missing timezone)
✗ 2024-01-15               (missing time)
✗ 1705315800               (Unix timestamp—not supported)

Per-Metric Timestamps

When batching historical data, per-metric timestamps are validated individually:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "metrics": [
    { "key": "vehicle.speed", "value": 60, "timestamp": "2024-01-15T10:29:55Z" },
    { "key": "vehicle.speed", "value": 65, "timestamp": "1990-01-01T00:00:00Z" }
  ]
}

The second metric would be rejected (too old) while the first is accepted.

Payload Size Limits

Validation Response

Failed validation returns a structured error:

{
  "error": {
    "code": "OUT_OF_BOUNDS",
    "message": "Metric 'engine.rpm' value 15000 is out of bounds [0, 8000]",
    "field": "metrics[2].value",
    "suggestion": "Check sensor calibration or unit conversion"
  }
}

Error Codes

Best Practices

1. Validate locally first — SDKs include validation; catch errors before transmission
2. Use canonical units — Convert at the edge, not at ingestion
3. Include timezone always — UTC (Z suffix) is preferred
4. Handle rejection gracefully — Log, alert, and retry with corrections
5. Monitor rejection rates — High rates indicate driver bugs or sensor issues

→ See Reference > Error Codes for complete error documentation