ADR-0005: Serialization and mandatory transport baselineLink to the section ADR-0005: Serialization and mandatory transport baseline
On this page
Status: Accepted 2026-10-14 — sponsor confirmed ("keep all") Date: 2026-10-14 Profiles affected: all
ContextLink to the section Context
Interoperability dies when every function has three equally valid transports. ONVIF's experience shows the value of a small mandatory baseline with precisely specified options.
Options consideredLink to the section Options considered
- Serialization: JSON vs Protobuf vs CBOR.
- Video: WebRTC vs RTSP/RTP vs SRT vs HLS/DASH.
- Telemetry and events: WebSocket vs MQTT vs gRPC streams.
- Configuration/commands: REST vs gRPC vs SOAP (ONVIF heritage).
DecisionLink to the section Decision
| Function | Mandatory (v1) | Defined alternatives |
|---|---|---|
| Serialization | JSON (UTF-8), RFC 8259 | Protobuf binding published as a non-normative annex once the JSON model is stable |
| Configuration, capabilities, commands | HTTPS REST (/univip/v1/...), OpenAPI 3.1 |
gRPC (future) |
| Session channel (telemetry, events, signaling, command status) | Secure WebSocket (RFC 6455 over TLS) carrying JSON envelopes | MQTT 5 over TLS with the topic mapping in spec/08-events.md |
| Live video | H.264 (Constrained Baseline or Main, ≤ Level 4.1 for the mandatory stream) over WebRTC, signaling over the session channel | H.265 over WebRTC; RTSP/RTP; SRT (contribution) |
| In-band metadata (recording) | MISB ST 0601 KLV in MPEG-2 TS when the device records or forwards TS | ONVIF metadata stream XML; out-of-band JSON telemetry with shared clock |
| Time | RFC 3339 UTC with millisecond or better precision; NTP or PTP or GNSS time source declared |
Rationale: JSON maximizes accessibility for VMS developers and matches vendor cloud APIs; WebSocket works through every proxy and NAT and needs no broker; WebRTC is what browsers and modern VMS clients already decode and matches ONVIF Profile V; H.264 is universal, H.265 common. MQTT is kept as the first alternative because DJI's Cloud API and ONVIF Profile V both use it. SRT is kept for high-latency, lossy contribution links.
ConsequencesLink to the section Consequences
- Every example in
examples/is JSON;schemas/are JSON Schema 2020-12. - Devices MUST ignore unknown JSON members to allow MINOR version additions.
- Conformance tests for Profile S test the mandatory column only; alternatives have their own optional test groups.
Open questionsLink to the section Open questions
- Whether to require H.264 High profile support on the client side. Current draft: clients MUST decode Constrained Baseline and Main; SHOULD decode High.
Whether MQTT should become co-mandatory.Resolved 2026-10-14 by the project sponsor: MQTT is not mandatory. The broker-free WebSocket session channel is the mandatory real-time binding; MQTT 5 remains a fully specified, separately conformance-tested alternative (Part 08 §8.7). Rationale indocs/transport-baseline-validation.md§2.3.- Whether devices SHOULD be required to offer RTSPS or SRT in addition to WebRTC for recorder ingest (current draft: SHOULD).