Part 08 — Events and the Event CatalogLink to the section Part 08 — Events and the Event Catalog#

Maturity: Draft · Profiles: S (mandatory set), C, N · Schema: univip.event.v0.2 (../schemas/event.schema.json)

8.1 ModelLink to the section 8.1 Model#

An event is a discrete notification. Events are published on the session channel as type: "event" envelopes and are retrievable for a limited history via GET /events. Events are either stateless (something happened) or stateful (a condition became active and later cleared); stateful events carry state: ACTIVE | CLEARED and the same topic.

8.2 Envelope payloadLink to the section 8.2 Envelope payload#

{
  "schema": "univip.event.v0.2",
  "event_id": "01J9ZC4B8X2V5N7P1Q3R6T9W0Y",
  "device_id": "urn:univip:acme:SN12345",
  "session_id": "flight-2026-10-15-1042",
  "topic": "vehicle.battery.low",
  "severity": "WARNING",
  "state": "ACTIVE",
  "timestamp": "2026-10-15T10:40:02.500Z",
  "source": { "component": "AIRCRAFT" },
  "data": { "battery_pct": 24, "threshold_pct": 25, "remaining_endurance_s": 310 },
  "related": { "command_id": null, "lease_id": null }
}

8.3 Standard catalogLink to the section 8.3 Standard catalog#

M = mandatory for Profile S devices that can detect the condition. A device that cannot detect a condition (for example a gateway with no battery access) MUST omit the topic from events.topics in capabilities. In particular, a gateway that reaches the vehicle only over the link whose loss it would report cannot tell link loss from the vehicle falling silent: it raises vehicle.telemetry.stale and does not advertise vehicle.link.lost unless another component (a dock or controller) reports the link state.

8.4 Ordering and deliveryLink to the section 8.4 Ordering and delivery#

• Events are delivered in the order of occurrence per device. event_id ULIDs are time-sortable.
• At-least-once delivery over the session channel. The device tracks, per configured endpoint, the last event it wrote to a session with that endpoint. After reconnection it MUST replay every event generated after that one, provided the disconnect lasted at most 15 minutes and produced at most 500 events; it MAY retain more. On the first session ever established with an endpoint nothing is replayed. Clients MUST deduplicate on event_id.
• A stateful condition is identified by its condition key: the topic plus data.code (vehicle.health.fault, vehicle.dock.fault), else data.lease_id (vehicle.control.pilot_override), else source.payload_id, else the topic alone. A CLEARED event closes the ACTIVE event with the same condition key; at most one condition per key is active.
• After every session establishment, the device MUST send each stateful event whose condition is still ACTIVE, with its original event_id. A client that kept its state drops it as a duplicate; one that lost its state learns the condition.

8.5 Standard fault codesLink to the section 8.5 Standard fault codes#

Devices SHOULD use these codes in health.faults[].code and vehicle.health.fault: IMU_CALIBRATION, COMPASS_INTERFERENCE, BAROMETER_FAULT, GNSS_SPOOFING_SUSPECTED, MOTOR_FAULT, ESC_FAULT, BATTERY_TEMPERATURE, BATTERY_CELL_IMBALANCE, GIMBAL_FAULT, CAMERA_FAULT, STORAGE_FULL, OBSTACLE_SENSOR_FAULT, RADIO_INTERFERENCE, FIRMWARE_MISMATCH, OTHER.

8.6 ONVIF topic mappingLink to the section 8.6 ONVIF topic mapping#

Annex A maps standard topics to ONVIF topic namespace equivalents for gateways that also expose ONVIF events (for example vehicle.camera.recording.started ↔ tns1:RecordingConfig/RecordingJobConfiguration where sensible, vehicle.health.fault ↔ tns1:Device/HardwareFailure/...). Where no ONVIF equivalent exists, gateways MUST use the tns1:Device/Trigger/… or a vendor namespace and MUST NOT misreport as an unrelated ONVIF topic.

8.7 MQTT 5 alternativeLink to the section 8.7 MQTT 5 alternative#

When the real-time plane uses MQTT 5:

Payloads are the same JSON envelopes as on the WebSocket channel. Telemetry uses QoS 0 with retained last sample; events and command status use QoS 1; vehicle.device.offline MUST be registered as the MQTT Will message. Topic aliases and user properties MAY be used; device_id MUST remain in the envelope regardless.