Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท MQTT and Messaging

MQTT Topics, Wildcards and Naming Best Practices

Design MQTT topic trees, use the + and # wildcards, avoid the common naming mistakes, and run a topic-matching function that behaves like a real broker.

A topic is the address of a message, and choosing good topics is the single most important design decision in an MQTT system. Topics are UTF-8 strings split into levels by a slash: building1/floor2/room204/temperature. The levels form a tree, and subscribers can use wildcards to listen to a whole branch at once.

In the previous lesson the broker matched topics by exact text. Here you will write the real matching rules, then learn a naming convention that scales from one sensor to a hundred thousand.

Levels and the topic tree

flowchart TD
  H["home"] --> K["kitchen"]
  H --> L["living"]
  K --> KT["temperature"]
  K --> KH["humidity"]
  L --> LT["temperature"]
  L --> LL["light"]

The topics are home/kitchen/temperature, home/kitchen/humidity, home/living/temperature and home/living/light.

Rules to remember:

  • Topics are case sensitive: Home/Temp and home/temp are different.
  • No spaces needed or recommended; use lowercase letters, digits, - and _.
  • A topic must have at least one character and must not contain the wildcard characters + or # when publishing.
  • A leading slash (/home) creates an empty first level. It is legal but almost always a mistake.
  • Topics starting with $ (such as $SYS/broker/uptime) are reserved for the broker. Wildcards at the first level do not match them.

The two wildcards

Wildcards exist only in subscriptions, never in publish topics.

Wildcard Meaning Example filter Matches
+ exactly one level home/+/temperature home/kitchen/temperature, home/living/temperature
# any number of levels, must be last home/kitchen/# home/kitchen, home/kitchen/temperature, home/kitchen/a/b

Note that home/kitchen/# also matches home/kitchen itself, because # can match zero levels. And +/+/temperature is a legal filter, while home/#/temperature and home/kit+/temp are not.

Writing the matcher

A broker must check each published topic against every subscription filter. The algorithm is simple: walk both strings level by level.

Node.js Topic filter matching

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at the fourth line: home/+ does not match home/kitchen/temperature because + covers just one level. If you want the whole subtree, you need #.

A broker with wildcards

Plug the matcher into the broker from the first lesson and you can see fan-out through wildcards. The status output counts how many subscribers each message reached.

Node.js Wildcard subscriptions in a broker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first message reaches three subscribers, the last reaches nobody. Each subscriber chose its own view of the same tree.

Naming best practices

Good names make wildcards useful; bad names make them useless. A convention used by many teams:

TEXT
<site>/<area>/<device-id>/<measurement-or-command>

For example plant7/line2/pump-14/pressure and plant7/line2/pump-14/cmd/start. Some guidelines:

  1. Put the general part first. Wildcards only match prefixes and single levels, so order levels from broad to narrow.
  2. Use one topic per kind of data. pump-14/pressure and pump-14/temp rather than a single pump-14/data with mixed payloads, unless you deliberately send one JSON snapshot.
  3. Separate state from commands. Devices publish state (.../state) and subscribe to commands (.../set). A mixed topic makes loops: a device receives its own message and republishes it.
  4. Put the device ID in the topic, not only in the payload. The broker's access control rules can then say "client pump-14 may publish only below plant7/line2/pump-14/".
  5. Do not subscribe to # in production. It forces the client to receive every message in the system.
  6. Keep topics short. The topic travels with every message; on tiny devices and cellular links bytes count.
  7. Avoid personal or secret data in topic names. Topics appear in broker logs and can be visible to anyone with subscribe rights.

Do not encode changing values in topics (like temp/21.5). Every distinct topic costs the broker memory, and subscribers cannot filter by value. Put values in the payload.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which filter matches farm/barn1/silo/level but NOT farm/barn1/silo/level/raw?

    + covers exactly one level, so the filter has four levels and cannot match the five-level topic. # would match both.
  2. 2. Where may wildcards be used?

    A publish topic must be a concrete name; wildcards belong to subscription filters.
  3. 3. Does home/kitchen/# match the topic home/kitchen?

    The parent level matches too: # stands for zero or more levels.
  4. 4. Which topic design is best for wildcard filtering?

    Broad to narrow levels, lowercase, no spaces, no values in the topic.

Summary

  • Topics are slash-separated, case-sensitive levels forming a tree.
  • + matches exactly one level, # matches the rest and must be last; wildcards belong to subscriptions only.
  • $-prefixed topics are broker-reserved and are not matched by first-level wildcards.
  • Design topics broad to narrow, one meaning per topic, state separate from commands, no values or secrets inside names.

Next: MQTT Quality of Service (QoS 0, 1, 2)