Why topic design matters
In MQTT, topics are the API. A clean topic structure makes systems discoverable and keeps subscribers simple. A messy structure creates hidden coupling and makes permissions painful.
Treat topic design as an information architecture task. You are naming the system for both humans and machines.
Choose a stable hierarchy
A common pattern is `/domain/entity/id/metric`. Example: `devices/thermostat/42/temperature`. It is readable and scales to many devices.
Avoid putting volatile values in the middle of the hierarchy, because it complicates wildcard subscriptions and permissions.
Depth vs readability
More levels add clarity but increase complexity. Find the minimal depth that captures ownership and entity type. Too deep and you make wildcard subscriptions brittle.
Use consistent separators and naming conventions. Hyphen-case or snake_case are fine as long as you stick to one.
Wildcard strategy
The `+` wildcard matches one level, and `#` matches everything below. Design topics so that wildcards align with logical grouping.
If you expect consumers to subscribe to “all devices in a building,” make sure that building is a stable hierarchy level.
Permissions and security
ACLs often map directly to topic patterns. A clear hierarchy makes it easier to grant least-privilege access.
Avoid mixing unrelated data under the same prefix. It complicates access control and auditing.
Versioning topic schemas
When topic structure must change, version it at the top level, e.g. `v2/devices/...`. This allows migration without breaking old clients.
Keep the old structure alive during transition and bridge messages when necessary.
Documenting topics
Provide a simple topic catalog. List the purpose, payload schema, QoS, retained behavior, and example values for each topic.
Good documentation turns a large MQTT system into a self-serve platform.