MQTT Topic Structure and Syntax

As a publish/subscribe messaging protocol, MQTT relies on hierarchical topics. Clients can publish messages on specific topics, and clients can receive published messages that match their current topic filters. MQTT topics are UTF-8 strings consisting of one or more topic levels that are separated by forward slash "/" characters, which creates a hierarchy of information for organizing topics. When creating topic strings it's important to note that Solace PubSub+ event brokers support topic strings with a maximum of 128 levels and a maximum length of 250 bytes, so an MQTT client connection that exceeds those limits will be closed.

The Solace PubSub+ allows messages to be exchanged between MQTT clients and non-MQTT clients (for example, SMF and REST clients) if those clients use an intersecting topic hierarchy. However, to deploy client applications that use different Solace-supported messaging protocols, architects and programmers should avoid using conflicting special characters and use a common topic syntax subset to ensure that topic filters are fulfilled in a consistent manner. For more information, refer to Topic Recommendations for Inter-protocol Messaging.

Special Characters in MQTT Topic Names and Filters

PubSub+ event brokers interpret special characters in MQTT topic names and filters as follows:

If the event broker receives the "+" or "#" characters in a topic name in a publish packet, it treats them as literal characters. Most MQTT APIs do not allow these characters in topic names, in accordance with the MQTT specification.
The event broker automatically creates a topic subscription beginning with the prefix #P2P/ for each client, which allows messages to be sent directly to that client (for example, in request/reply scenarios). However, the leading "#" in #P2P is not valid MQTT syntax. Therefore, to make use of these special Solace subscriptions, MQTT clients can use the string _P2P instead of #P2P. The event broker considers these two strings to be equivalent.
A leading "!" in an MQTT topic name or topic filter is treated the same way as a leading "!" in an SMF topic or subscription. For more information, refer to System-Level Subscription Exception Configuration.
An MQTT topic filter with the format $share/{ShareName}/{filter} indicates a shared subscription. For more information, refer to Shared Subscriptions.
An MQTT topic filter starting with $noexport indicates that the event broker should not export shared subscriptions. See Special Solace MQTT Topics below for details.

Topic Recommendations for Inter-protocol Messaging

MQTT clients can receive messages published by non-MQTT clients (for example, SMF or REST clients), and non-MQTT clients can receive messages published by MQTT clients, when an intersecting topic hierarchy is used by the MQTT and non-MQTT clients. Applications that expect to communicate between protocols should avoid conflicting special characters and use a common topic syntax subset.

Specifically, this means applications must:

Avoid using the "+" character. It is illegal in an MQTT topic name. Although SMF treats the "+" character in an MQTT topic name as a literal, an MQTT API may block it.
Avoid using the "#" character. It is illegal in an MQTT topic name. Although SMF treats the "#" character in an MQTT topic name as a literal, an MQTT API may block it.
Avoid using the "*" character. SMF treats "*" character as a wildcard, but MQTT treats it as a literal. SMF clients will not necessarily be able to subscribe to topics that include this character.
Avoid using the ">" character as a standalone final topic level. SMF treats the ">" character as a wildcard, but MQTT treats it is a literal. As a result, SMF clients that subscribe to such topics may attract additional traffic.
Avoid using the "$" character at the start of a topic. In MQTT, topic names starting with "$" are reserved for use by server implementations and should not be used by clients. This makes such topics inappropriate for client-to-client messaging.
Avoid empty topic levels. MQTT supports empty topic levels, and Solace PubSub+ event brokers Version 7.1.1 or greater allow empty topic levels in SMF topics. However, there are some limitations to using empty topic levels with SMF topics:
- Client applications using Solace messaging APIs can publish to topics with empty levels, but they cannot use topic filters or subscriptions with empty levels.
- ACL profiles do not allow SMF publishing or subscribing topic exceptions that have empty topic levels.

Using Subscription Managers with MQTT Clients

Client applications that are configured as Subscription Managers on a Message VPN may add or remove topic filters at QoS 0 on behalf of other clients within the same Message VPN.(For more information, refer to Managing Subscriptions on Behalf of Other Clients.)

Although you can use Subscription Manager clients to add or remove topic filters for MQTT clients, those topic filters may only use SMF syntax. Therefore, to avoid subscription parse errors for the MQTT clients, those topic filters should be written with the following points in mind:

The ">" SMF wildcard is not allowed because there is no MQTT equivalent—in SMF, the ">" character must match 1 or more topic levels, whereas in MQTT, the "#" character must match 0 or more topic levels.
Instead of the MQTT "#" wildcard, the topic filter must use the ASCII character 0x03.
Instead of the MQTT "+" wildcard, the topic filter must use the SMF "*" wildcard for MQTT clients. The "*" and "+" wildcards are exact equivalents.

Special Solace MQTT Topics

PubSub+ event brokers use a number of special topics to implement certain Solace messaging features. Each of these topics begin with the $ character, which is then followed by a specific, reserved sequence of characters.

Topic	Description
$noexport/	Prevents the subscription, shared or otherwise, from being exposed to MNR or DMR. For more information, see Reserved Topics.
$SYS/client/client-name	When an MQTT client subscribes to this special topic, the event broker responds with the client name for the MQTT session. The client name is required to configure on-behalf-of subscription managers. For more information, see Requesting Session Info with Special Topics and Managing Subscriptions on Behalf of Other Clients.
$SYS/client/reply-to	When an MQTT client subscribes to this special topic, the event broker responds with the reply-to destination for the MQTT client. In other words, the body of the message published to this topic provides the reply-to topic/destination that is reserved for the client. The reply-to destination is needed to implement the request/reply messaging pattern. For more information, see Requesting Session Info with Special Topics. In MQTT 5.0, the need for the reply-to topic has been superseded by the Response Information added in the CONNECT/CONNACK exchange. For details, see 3.2 CONNACK – Connect acknowledgement.

Topic

Description

$noexport/

Prevents the subscription, shared or otherwise, from being exposed to MNR or DMR.

For more information, see Reserved Topics.

$SYS/client/client-name

When an MQTT client subscribes to this special topic, the event broker responds with the client name for the MQTT session. The client name is required to configure on-behalf-of subscription managers. For more information, see Requesting Session Info with Special Topics and Managing Subscriptions on Behalf of Other Clients.

$SYS/client/reply-to

When an MQTT client subscribes to this special topic, the event broker responds with the reply-to destination for the MQTT client. In other words, the body of the message published to this topic provides the reply-to topic/destination that is reserved for the client. The reply-to destination is needed to implement the request/reply messaging pattern. For more information, see Requesting Session Info with Special Topics.

In MQTT 5.0, the need for the reply-to topic has been superseded by the Response Information added in the CONNECT/CONNACK exchange. For details, see 3.2 CONNACK – Connect acknowledgement.

Provide feedback