Once a Unified Namespace is up, names are the hardest thing to change: every rename affects every system subscribed to that branch. Naming decisions are therefore better treated as a contract than as a technical detail.
The hierarchy, using ISA-95
The ISA-95 equipment hierarchy gives a UNS a natural skeleton. A common layout:
| Level | Meaning | Example |
|---|---|---|
| Enterprise | Company or business unit | acme |
| Site | Physical plant | istanbul |
| Area | Section within the site | packaging |
| Line | Production line / work center | line-3 |
| Cell | Optional sub-division | filling |
| Asset | Machine or equipment | filler-02 |
| Metric | Measurement or state | temperature |
The result: acme/istanbul/packaging/line-3/filling/filler-02/temperature. Every plant has different needs and you may skip levels such as the cell, but order and meaning must stay consistent within the same enterprise.
Constraints that MQTT brings
- Topic names are case sensitive:
Line-3andline-3are different branches. /is the level separator and cannot be used inside a name.- The wildcards
+(single level) and#(multi level) exist only in subscription filters; they cannot appear in the topic name you publish to. - Topics starting with
$are generally reserved for the broker’s own purposes (for example$SYS); do not start your enterprise name with it. - In practice topics should be far shorter than the protocol limit; very long paths add maintenance and network overhead.
Practical naming rules
- Lowercase, hyphens: Avoid spaces and mixed case.
filler-02reads and types safely. - ASCII: Accented characters can cause trouble across systems; normalize them.
- General to specific: Keep the order fixed so subscriptions can target branches.
- Stable names: Do not put information that can change (order number, shift, operator) in the path; carry it in the payload.
- Put the unit in the model, not the path: a
temperaturetopic with a payload such as{"value":74.2,"unit":"°C"}rather thantemperature-c. - Limit the depth: Every extra level complicates subscription filters and access rules.
- One language, one dictionary: Avoid mixing “hat/line” or “makine/machine”; keep a naming dictionary.
How it differs with Sparkplug B
Sparkplug B imposes its own topic structure: spBv1.0/{group_id}/{message_type}/{edge_node_id}[/{device_id}]. There, the ISA-95 hierarchy is not in the topic path but typically carried in metric names or in group/node/device mappings. In a plain-MQTT UNS the hierarchy sits directly in the path. Which one you choose depends on your need for device discovery and state management, on what your products support and on your team’s preference. Our Sparkplug B & UNS Topic Builder lets you try both structures; it is free and runs in the browser.
Designing subscriptions and access
A good hierarchy makes subscribing easy too:
acme/istanbul/packaging/line-3/#— all data of a lineacme/istanbul/+/+/+/state— the state of every asset in the plant (when the number of levels is fixed)
Access control can also be defined by branch: a line gateway may write only to its own branch, a dashboard may only read. This limits both exposure and the spread of mistakes. For where brokers sit in the network, see our OT network segmentation article.
Common mistakes
- Putting time or order information in the topic (it creates an unbounded number of branches).
- Using a different hierarchy in every project.
- Renaming without removing the old branch, so two copies of the data are published.
- Forgetting to clear retained messages; see retain and Last Will for details.
