An MQTT topic convention can look tidy during a pilot and become unmanageable after the second plant, a new equipment vendor, or the first external integration. The cost is not only cosmetic. Inconsistent paths make subscriptions overbroad, access rules difficult to review, and equipment identity ambiguous downstream.
A useful hierarchy gives a message enough stable context for routing and authorization without turning every changing telemetry value into a topic level. It is a namespace design decision, not an MQTT requirement and not a replacement for a governed asset model.
Start with the decisions a topic must support
Before choosing names, list the people and systems that will subscribe. A site operations team may need one line’s telemetry. A historian collector may need all approved telemetry. A maintenance application may need only condition events for selected assets. Security administrators need topic patterns that can be translated into broker access-control rules.
For each use case, identify stable dimensions that are useful in a route: site, area, line, equipment, and message class are common candidates. Do not include a dimension merely because it exists in an engineering drawing. A level earns its place when subscribers, routing, ownership, or authorization need it.
Use stable identity levels and a clear message class
One illustrative plain-MQTT structure is:
industrial/{site}/{area}/{line}/{equipment_id}/{message_class}
Examples might be:
industrial/shanghai/packaging/line-2/filler-07/telemetry
industrial/shanghai/packaging/line-2/filler-07/event
industrial/shanghai/packaging/line-2/filler-07/health
This is an organizational convention, not a protocol-mandated industrial schema. The key is that each level has one documented meaning. filler-07 is a stable equipment identifier; telemetry, event, and health classify the message purpose. Values such as pressure, mode, batch number, or a temporary alarm state normally belong in the payload, because they change message by message.
Avoid paths such as plant-a/line-2/filler-07/running/pressure. A device state is transient, so using it as an identity level splits the same asset across routes as it operates. It also creates subscriptions and access rules that have to anticipate every state spelling.
Design subscriptions from the hierarchy, not after it
MQTT uses / to separate topic levels. The + wildcard matches one complete level in a topic filter, while # matches the parent and any remaining levels and must be the last character of the filter. Wildcards belong in subscription filters, not published topic names. Topic names are case-sensitive, and the broker does not normalize them. See the OASIS MQTT 5.0 specification for the exact matching rules.
With the example namespace, these filters have readable intent:
| Consumer need | Topic filter | Scope |
|---|---|---|
| One asset’s telemetry | industrial/shanghai/packaging/line-2/filler-07/telemetry | One message class for one asset |
| One line’s telemetry | industrial/shanghai/packaging/line-2/+/telemetry | Telemetry for every equipment identifier directly under the line |
| All messages for one asset | industrial/shanghai/packaging/line-2/filler-07/# | The asset’s message classes and any later child levels |
| Whole site | industrial/shanghai/# | Broad operational scope; use deliberately |
Keep hierarchy depth stable. If one site inserts an equipment-type level but another does not, a filter that works in one plant can silently miss or overmatch another. Do not use # in a routine application subscription merely because it is convenient; its breadth makes least-privilege access and message-rate control harder.
Treat naming as a governed interface
Define a concise naming standard before devices publish at scale:
- Choose lowercase or another single case convention; MQTT treats
Line-2andline-2as different names. - Use controlled site and equipment identifiers rather than display labels that change with operators or projects.
- Reserve message-class names and document their intended payload contract.
- Decide how a renamed asset, retired line, or moved machine is handled without silently changing the historical source identity.
- Version a breaking payload or namespace change explicitly, such as a documented
v2level, rather than changing the meaning of an existing path without notice.
The MQTT specification permits many valid topic names, including empty levels and leading or trailing separators. Those are protocol facts, not reasons to use them in an industrial convention. Set stricter organizational rules where they improve clarity, auditability, and automation.
Connect topic paths to access control and routing
A well-designed hierarchy lets a broker policy express intent. A packaging-line maintenance service can be authorized to subscribe under its approved line and message classes, while a central historian service can subscribe to the telemetry branches it is responsible for. The exact ACL syntax and behavior are broker-specific, so validate policies with the deployed broker rather than assuming that a topic pattern is authorization by itself.
The same structure helps routing. A collector can subscribe to a stable telemetry branch without parsing display-name text from each message. TDengine’s MQTT ingestion documentation describes Topic Analysis, which parses topic levels into variables for subsequent payload transformations. That is a mapping capability, not proof that a topic path automatically creates an asset hierarchy or validates equipment identity.
For an industrial program that needs governed equipment context above raw time-series data, TDengine IDMP is the relevant product destination. Its asset trees and data-model capabilities should be configured from reviewed context; an MQTT topic hierarchy can contribute source context, but it does not by itself become an ontology.
Review the hierarchy against realistic change
Before standardizing it, test a proposed namespace with real subscription and governance questions:
- Can each intended consumer subscribe to exactly its required scope without an overly broad wildcard?
- Can an ACL reviewer tell what a client may publish and receive from the topic pattern?
- Does every equipment identifier remain stable across a rename, move, and controller replacement?
- Can a new message class be added without changing existing paths or subscriber meaning?
- Can downstream collectors associate topic identity with approved equipment context without assuming it is a complete asset model?
Run the test with at least two plants and several equipment classes. A hierarchy that is elegant for one skid but inconsistent across sites will create long-lived integration debt. The best topic design is predictable enough that routing, permissions, historians, and operators all interpret the same path consistently.
