Topics

What Are Topics?

In a publish/subscribe messaging system, a topic represents a named channel or subject used to categorize and route messages between publishers and subscribers. When messages are published to a topic, all subscribers to that topic receive those messages. This approach allows for efficient one-to-many communication, where multiple consumers can independently subscribe to specific subjects relevant to their application.

Topics are typically structured as hierarchical strings, making it easy to organize, filter, and scale message routing according to subject matter.

• Example: devices.kitchen.temperature, orders.completed.us.nyc, or simply broadcast
• This hierarchy allows applications to subscribe broadly (e.g., devices.>, devices.*.temperature) or narrowly (e.g., devices.kitchen.temperature), depending on their needs. More about this in the Wildcard Behaviour section.

---

Topic Naming Rules

To ensure consistent and valid topic names, please follow these rules when defining your topics:

• No dollar signs ($):
  The topic string must not contain the $ character anywhere.

• Topics cannot have spaces or be null

• > can be present only at the end of a topic (after a .)

• Topic Format:
  token[.token …][.> or .*]

  Token definition:
  Each token consists of one or more characters from the following set:
  A-Z a-z 0-9 _ * ~ -
  (letters, digits, underscore, asterisk, tilde, or hyphen)

• Token restrictions:

  • Tokens cannot be empty.
  • No consecutive dots (..).
  • No leading or trailing dots

• Case sensitivity:
  Topic names are case-sensitive — uppercase and lowercase letters are treated as distinct.

Adhering to these naming conventions ensures compatibility with the messaging system and enables proper topic matching and subscription behavior.

---

Wildcard Behaviour

Wildcards let subscribers match messages from multiple related topics without specifying each one individually:

• Asterisk (*): Matches exactly one token at the position it appears.
  • devices.*.temperature matches devices.kitchen.temperature and devices.livingroom.temperature.
• Greater-than (>): Matches one or more tokens at the end of a subject and must only appear as the last token.
  • devices.> matches devices.kitchen.temperature, devices.kitchen.humidity, and devices.livingroom.temperature.
  • > matches all topics.
• Mixing wildcards: You can use multiple * in a topic and can mix both wildcards.
  • *.us.> matches topics beginning with any token, followed by us, then any other sequence (e.g., temp.us.nyc, humidity.us.la.outdoor).

Wildcard use is only supported in subscriptions, not when publishing, and allows for highly flexible, scalable subscription patterns.

By defining and using topics with hierarchical names and wildcards, you can build scalable, flexible message routing in your applications and ensure that each component or service receives only the messages it needs.

---

Reserved Topics

These are topics reserved for use across all SDKs. Clients cannot publish / subscribe to these topics

• CONNECTED
• DISCONNECTED
• RECONNECT
• RECONNECTED
• RECONNECTING
• RECONN_FAIL
• MESSAGE_RESEND

---

Examples

All client SDKs have built in topic validators built in as a utility.

// Select a platform to see code

Examples of valid topics:

• sensor.data.temperature
• user.signup.europe.london
• foo.bar
• system.error.critical
• foo
• foo.bar
• *
• foo.*
• *.bar
• foo.*.baz
• >
• foo.>
• foo.bar.>
• *.*.>
• alpha_beta
• alpha-beta
• alpha~beta
• sensor.temperature
• metric.cpu.load
• *.*
• metrics.>

Invalid topic examples:

• $foo
• foo$
• foo.$.bar
• foo..bar
• .foo
• foo.
• foo.>.bar
• >foo
• foo>bar
• foo.>bar
• foo.bar.>.
• foo bar
• foo/bar
• foo#bar
• ..
• .>
• foo..
• .
• >.
• foo,baz
• αbeta
• foo|bar
• foo;bar
• foo:bar
• foo%bar
• foo.*.>.bar
• foo.*.>.
• foo.*..bar
• foo.>.bar
• foo>

Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️