The short answer

A good message contract identifies source, time, schema, and intent while keeping business events distinct from raw telemetry.

What matters in practice

  • Event IDs support deduplication.
  • Device time may be uncertain.
  • Commands need acknowledgement and terminal outcome.
  1. Use explicit schema versions.
  2. Keep envelopes small and consistent.
  3. Validate at producer and consumer boundaries.

Boundaries and failure modes

  • Overloading one data message for every intent.
  • Relying on field order.
  • Treating broker delivery as command completion.

Scope and message classes

Separate telemetry, events, commands, acknowledgements, and state. Telemetry is an observation with value, unit, quality, source time, and sequence where available. An event is an immutable discrete occurrence with stable ID and type. A command requests an action with ID, target, parameters, expiry, preconditions, and issuer context. An acknowledgement reports accepted, rejected, started, completed, failed, expired, or superseded. State is a versioned current view with freshness.

This model covers application payloads, not authentication, transport guarantees, or sensor accuracy.

Envelope and time semantics

Use a small envelope containing message ID, type, source, occurrence time, sequence scope, schema identity, and data. State whether time came from device, gateway, or platform. Preserve receive time separately. Use string identifiers when values can exceed consumer integer precision. Keep mutable customer labels in registries rather than copying them into every device message.

Transport metadata can remain transport-specific while a message is on one hop, but preserve any field required after bridging or storage. Never use MQTT packet identifiers as business idempotency keys.

Evolution rules

Prefer additive optional fields with documented defaults. Consumers may ignore unknown fields only when safe. Never change type, unit, or meaning in place. Breaking changes need a new schema identity and a coexistence plan. Topic version and payload version solve different contracts.

Maintain schemas, valid examples, and invalid counterexamples in version control. Test every supported producer against consumers. Validate at ingress and retain bounded, redacted evidence of rejection.

Implementation steps

  1. Inventory flows and classify message type.
  2. Define identifiers, time, sequence, units, quality, and lifecycle.
  3. Select encoding from device constraints and ecosystem support.
  4. Write schemas and examples.
  5. Define compatibility and deprecation.
  6. Add idempotency and correlation to events and commands.
  7. Test producers, gateways, and consumers in CI.
  8. Observe versions, validation failures, duplicates, and lag.
  9. Exercise mixed versions, replay, reboot, and clock loss.

Failure modes

A temperature without unit is ambiguous. Device clocks can move backward. Generating a new command ID on retry defeats idempotency. Publishing zero on timeout destroys missing-data meaning. Unknown enum values treated as success make additive evolution unsafe. Binary integers converted through JavaScript numbers can lose precision. A gateway that rewrites timestamps destroys provenance.

Implementation checklist

  • Message classes have distinct contracts.
  • Identity, time, units, quality, sequence, and schema are explicit.
  • Commands include ID, expiry, preconditions, and outcomes.
  • Missing values remain distinguishable.
  • In-place semantic changes are prohibited.
  • Schemas and compatibility tests live in version control.
  • Rejected and unknown versions are observable.
  • Mixed-version and duplicate tests pass.

Governance and verification evidence

Assign an owner to each schema and publish its compatibility promise, supported versions, retention, and removal date. A registry entry should link the schema to producers, consumers, topics or endpoints, examples, and change history. Code generation can reduce typing errors but does not decide semantics; reviewers still need to check units, nullability, enum evolution, privacy, and what a missing field means.

Build a contract suite with golden messages from every supported firmware and gateway. Run them through validation, storage, analytics, rules, exports, and command handlers. Add malformed lengths, unknown enum values, extra fields, missing optional and required values, duplicate IDs, clock rollback, sequence reset, out-of-order arrival, and values at numeric boundaries. Verify behavior during a rolling deployment where old and new producers and consumers coexist.

Keep evidence of rejected messages by reason, version adoption, unknown fields, duplicate suppression, clock skew, and consumer lag, with payload redaction and bounded retention. A sudden validation-success rate of one hundred percent can be suspicious if gateways silently drop bad input before measurement. Trace one message from device observation to business outcome while preserving identity, timestamps, quality, and correlation. Retire an old version only after traffic reaches zero, retained or queued copies expire, and authorization or routing rules no longer accept it.

Document ownership of semantic conversions. When a gateway changes units, aggregates samples, fills values, or maps vendor enums, the output must identify that transformation and its version. Otherwise downstream consumers attribute derived data incorrectly to the original device.

Primary sources

The CloudEvents specification is a useful event-envelope reference. MQTT 5.0 defines transport properties, expiry, and correlation data. JSON contracts can use JSON Schema 2020-12; binary formats should follow their normative schema specifications.