Skip to main content

Topics

What Are Topics?​

In RelayX, a topic is a named address that messages are published to and delivered from.

Topics exist for one reason: routing messages.

When a producer publishes a message, it publishes it to a topic.
When a subscriber subscribes, it subscribes to one or more topics.

During normal operation, messages published to a topic are delivered to all subscribers of that topic.

Topics do not process messages.
Topics do not change message behavior.
Topics do not add delivery guarantees.

They only decide which subscribers receive which messages.

How Topics Are Used​

Topics are represented as strings. These strings are used by RelayX to match published messages with subscriptions.

Common examples:

  • devices.kitchen.temperature
  • orders.completed.us.nyc
  • broadcast

Topics are often written in a hierarchical form to make routing easier to reason about, but the hierarchy itself does not change how messages behave.

More about matching behavior is explained in the Wildcard Behaviour section.

Topic Naming Rules​

To ensure consistent behavior across all SDKs, topic names must follow these rules:

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

  • Topics cannot contain spaces and cannot be empty

  • Wildcard placement

    • > may appear only at the end of a topic and only after a .

  • Topic format
    token[.token …][.> or .*]

    Token definition
    Each token consists of one or more characters from:
    A-Z a-z 0-9 _ * ~ -

  • Token restrictions

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

  • Case sensitivity
    Topic names are case-sensitive.
    Foo.Bar and foo.bar are different topics.

Wildcard Behaviour​

Wildcards allow subscribers to receive messages from multiple related topics without subscribing to each topic individually.

Wildcards are only supported in subscriptions, not when publishing.

Asterisk (*)​

Matches exactly one token.

  • devices.*.temperature matches:
    • devices.kitchen.temperature
    • devices.livingroom.temperature

Greater-than (>)​

Matches one or more tokens at the end of a topic and must be the final token.

  • devices.> matches:

    • devices.kitchen.temperature
    • devices.kitchen.humidity
    • devices.livingroom.temperature

  • > matches all topics

Mixing wildcards​

You may use multiple * tokens and mix * with >.

  • *.us.> matches:
    • temp.us.nyc
    • humidity.us.la.outdoor
warning

Wildcards affect subscription matching only.
They do not affect message ordering, delivery guarantees, or retries.

Reserved Topics​

The following topics are reserved and cannot be published to or subscribed to by clients:

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

What Topics Do Not Do​

Topics do not:

  • Control message ordering
  • Control retries or redelivery
  • Affect deduplication
  • Isolate failures between subscribers
  • Act as queues or workflow stages

All message semantics are defined by the messaging system itself, not by the topic.

Examples​

Valid topics​

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

Invalid topics​

  • $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>


Need Help?

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