Direct answer

Build MQTT topics from durable resource identity, message direction, and contract purpose. Keep location, display names, ownership, firmware, and other mutable metadata in the payload or registry. A useful starting shape is v1/{tenantId}/devices/{deviceId}/telemetry, with separate branches for events, state, commands, and command acknowledgements. The hierarchy must make least-privilege ACLs straightforward; readability alone is not enough.

Scope and non-scope

Topic design controls routing, subscription breadth, authorization boundaries, retained-state placement, and operational discovery. It does not define the complete message schema, guarantee tenant isolation by itself, or replace a device registry. Topic names are visible to brokers, bridges, logs, and often operators, so they must not contain secrets or unnecessary personal data.

This guide assumes centrally managed devices and a broker that can derive ACL variables from authenticated identity. Public broadcast systems and ad hoc consumer applications may need different discovery conventions.

Design criteria

Start with stable identifiers. A device ID can remain in a topic for the device lifetime. A store name, room number, customer display name, or organizational team changes and creates migrations, aliases, and stale subscriptions. Use opaque but supportable identifiers; operators can resolve them through inventory tooling.

Make direction visible. Telemetry and events flow from a device toward services. Commands flow toward the device. Acknowledgements and reported state return from it. Separating these branches prevents an ACL intended for telemetry from accidentally permitting command publication. Avoid a generic messages branch that forces every consumer to inspect payloads before knowing authority or intent.

Place the tenant boundary early enough for broker authorization and operational quotas. Never trust a tenant value merely because the client wrote it in the topic. Bind the authenticated principal to its permitted tenant and device path. Service accounts need similarly explicit read or write scopes.

Version only breaking contracts. A top-level v1 is useful when topic shape, routing meaning, or authorization changes incompatibly. Do not increment it for every payload field; payload schemas need their own compatibility policy. Keep topic levels short and ASCII-safe, define case sensitivity, and prohibit empty levels and leading or trailing separators.

A practical hierarchy

v1/{tenantId}/devices/{deviceId}/telemetry
v1/{tenantId}/devices/{deviceId}/events
v1/{tenantId}/devices/{deviceId}/state/reported
v1/{tenantId}/devices/{deviceId}/commands/{commandName}
v1/{tenantId}/devices/{deviceId}/command-acks/{commandId}

Use a payload field rather than another topic level when the value is high-cardinality, mutable, sensitive, or not needed for routing. Do not put timestamps, measurement values, access tokens, email addresses, or arbitrary user input in a topic.

Implementation steps

  1. Inventory publishers, subscribers, message directions, and required fan-out.
  2. Draw the authorization matrix before finalizing names.
  3. Define a grammar with allowed characters, maximum bytes, levels, and reserved prefixes.
  4. Specify wildcard subscriptions explicitly; treat # as a privileged capability.
  5. Bind device credentials to exact publish and subscribe templates at the broker.
  6. Add topic validation to firmware tests, service tests, and deployment policy.
  7. Exercise ownership transfer, tenant migration, bridge routing, and version coexistence.
  8. Publish examples and counterexamples as part of the message contract.

Failure modes

Embedding mutable geography creates mass subscription changes when assets move. A wildcard write such as v1/tenant/# lets one compromised device impersonate others. Shared subscriptions can distribute work but change consumer ordering assumptions. Retaining event streams can replay an old event to every new subscriber; retained messages should represent current state only when that semantic is explicit. A bridge that rewrites prefixes can bypass assumptions made by downstream ACLs. Very broad wildcard subscriptions can also create unexpected fan-out and broker load.

Implementation checklist

  • Every level has a documented routing or authorization purpose.
  • Tenant and device values are verified from authenticated identity.
  • Commands and device-originated data use separate write scopes.
  • Mutable metadata and sensitive values stay out of topic names.
  • Wildcard subscriptions have owners, limits, and load tests.
  • Retained-message policy is defined per branch.
  • Breaking topic versions can coexist during migration.
  • CI rejects malformed, unauthorized, and noncanonical topics.

Governance and review evidence

Own the topic grammar like an API. Store it beside payload schemas, ACL templates, and compatibility tests. A proposed topic change should show affected publishers, subscriptions, retained values, bridges, dashboards, and migration duration. Keep examples from production-shaped clients rather than accepting diagrams alone. Review observed topic cardinality and wildcard fan-out so undocumented branches are detected early. When a branch is deprecated, stop new publishers first, monitor remaining traffic, then remove subscriptions and authorization. Never leave a broad compatibility ACL indefinitely; its expiry and owner belong in the migration plan.

Compatibility acceptance

Before publishing a new topic version, run old and new publishers with old and new consumers through the same broker policy. Verify that bridges, retained values, dashboards, alerts, and audit exports do not merge versions accidentally. Define which side dual-publishes or dual-subscribes, for how long, and how duplicate business events are prevented.

Inspect topics as UTF-8 byte strings, not visual labels. MQTT topic names are case-sensitive and may contain characters that look alike. Restrict the production grammar to a conservative reviewed subset unless a real requirement justifies more. Enforce maximum topic bytes before connection traffic reaches the broker. A clean migration ends by removing old write permission, retained state, and wildcard compatibility filters; traffic reaching zero is evidence, not permission to leave obsolete authority in place forever.

Primary sources

The OASIS MQTT 5.0 specification sections 4.7 and 4.8 define topic names, filters, wildcards, and shared subscriptions. Broker-specific ACL syntax is not standardized; verify substitution variables, deny precedence, retained-message authorization, and bridge behavior against the selected broker’s official documentation.