Industrial MQTT topic design: names, payloads and data contracts
Design a stable telemetry namespace with identity, timestamps, units, quality and schema ownership before connecting dashboards and consumers.
A topic hierarchy helps route messages. It does not, by itself, tell a consumer whether a temperature is Celsius, when it was sampled, or whether the instrument is healthy. A usable industrial data contract defines both the topic's identity and the payload's meaning.
Separate identity from presentation
An illustrative topic is site-a/area-2/line-4/filler-01/telemetry. Choose stable asset identifiers and keep display names in metadata so a renamed area does not force every consumer to resubscribe. Define the namespace owner and a migration rule before duplicating similar trees across gateways.
Document the intended hierarchy, case conventions and allowed characters. In MQTT, topic names are case-sensitive, and the + and # characters have wildcard meanings in subscription filters. Do not treat a filter as a literal publishing topic.
Define the payload contract
| Field | Example meaning | Decision to document |
|---|---|---|
| Asset ID | Stable machine identity | Registry and rename policy |
| Timestamp | When the source sampled the value | Clock, time zone and stale threshold |
| Value and unit | A numeric reading and engineering unit | Range, datatype and scaling |
| Quality | Valid, uncertain or bad observation | Mapping from source diagnostics |
| Schema version | Payload contract revision | Compatibility and migration rules |
| Sequence or event ID | Duplicate and gap handling | Scope and reset behavior |
The data-contract worksheet is a starting point for those decisions. It deliberately keeps broker credentials out of the record.
Retained values are not a history database
A retained message helps a new subscriber receive the latest retained value for a matching topic. Its presence does not prove that the device is still connected or the value is fresh. Include source timestamps and define stale behavior. Use explicit state conventions or an appropriate framework such as Sparkplug when device state needs shared semantics.
Likewise, QoS concerns protocol delivery between participating clients and brokers. A consumer still needs application-level rules for duplicate events, reconnects, replay and side effects. Review the MQTT delivery guide before selecting a level by intuition.
Keep commands under a different contract
Telemetry and commands have different consequences. Separate their namespaces, authorization, acknowledgment and lifecycle requirements. Do not reuse a retained telemetry convention for a machine command without a process-specific design. Gateways should expose connection and source quality without allowing a dashboard outage to interfere with basic control.
Before rollout, test a late subscriber, a reconnect, a stale source, a duplicate and an incompatible payload version. Record the expected consumer behavior for each. Continue through the industrial data path and UNS introduction.
Primary specification
OASIS MQTT 5.0 specifies topics, filters, retained messages and delivery behavior. The hierarchy and payload fields above are design suggestions, not a standard MQTT payload schema.
Cite this page: Industrial MQTT topic design: names, payloads and data contracts
, Shopfloor, 2026-10-11. https://shopfloor.space/articles/mqtt-topic-design-industrial-data/