MQTT starts simple and becomes chaotic quickly if naming, ownership, and evolution rules are not defined. Topic governance is not bureaucracy. It is how teams avoid accidental coupling and fragile integrations.
1. Topic hierarchy principles
A practical hierarchy typically encodes:
- environment
- site or region
- device class
- device ID
- channel purpose (state, command, event)
Make hierarchy semantic but not overly deep.
2. Separate telemetry, command, and lifecycle
Do not mix data types in one topic family. Keep clear boundaries:
- telemetry: periodic measurements
- command: requested actions
- lifecycle: online/offline, version, health
This improves ACL control and consumer logic.
3. Payload contract ownership
Every topic family needs an owner team and schema definition. Include:
- required fields
- units and precision
- timestamp semantics
- compatibility rules
No owner means undocumented breaking changes.
4. Versioning strategy
When payload changes are unavoidable:
- prefer backward-compatible additions
- introduce explicit version channel when breaking
- deprecate old versions with timeline
Silent schema drift is one of the hardest integration failures to detect.
5. ACL model aligned with namespace
Topic namespace should support security policy directly:
- device can publish only own telemetry path
- device can subscribe only its command path
- admin tools have audited elevated scope
If namespace and ACL goals conflict, redesign namespace.
6. Wildcard usage policy
Wildcards are useful but dangerous at scale. Restrict wildcard consumers to infrastructure tools and monitored services.
Application services should subscribe narrowly when possible.
7. Documentation and linting
Treat topic catalog as code:
- machine-readable registry
- schema lint checks in CI
- example payloads per topic
Automated checks prevent accidental naming regressions.
8. Migration playbook
For major restructures:
- run dual-publish period
- track consumer migration progress
- remove legacy topics only after explicit cutover approval
A forced overnight switch usually causes hidden data loss.
Final note
Good MQTT governance keeps systems evolvable. Naming consistency, ownership, and compatibility policy are foundational once projects move beyond a handful of devices.