Understanding Topics

We mentioned above that MQTT separates messages via topics. These topics exist in a hierarchical tree. For example: /Sports/American Football/NFL/Bears/Scores and /Sports/Austrialian Football/AFL/Crows/Scores are two equally valid topic paths. While it isn’t a rule that topics go from large scopes (all of sports) to small scopes (team scores), it is a very common idiom to do so.

This is due to the semantics behind subscriptions. There are three kinds of subscription. The first is a regular subscription: /Sports/Golf/Tournaments/Winners (here is a good time to note that a topic consists of any UTF8 character, excluding the (“/”,“+”,and “#” runes)

The last two subscriptions are wildcard subscriptions. That means they are subscribed to multiple topics simultaneously. The first wildcard we’ll discuss is the ‘single level wildcard’, otherwise known as the “+” wildcard. The single level wildcard allows a subscription to skip an entire level of the topic’s path. In our experience this is the more difficult of the two types of wildcard to visualize, so we’ll use some examples.

Let’s say we have a single level wildcard in our subscription. /Sports/Tennis/+/Winners

Publish Number Publish Topic Receives
1 /Sports/Tennis/Wimbledon/Winners
2 /Sports/Tennis/French Open/Winners
3 /Sports/Tennis/Winners
4 /Sports/Tennis/US Open/Mixed Doubles/Winners
5 /Sports/Professional Eating/Oysters/Winners

Okay, let’s break down what happened. 1 & 2 matched because they had the same path preceding the wildcard, and the same path after the wildcard. The only difference between the two was the topic section that took place in the wildcard. 3 matched preceding the wildcard, but then didn’t have anything after. 4 matched the preceding, but had too much going on after the single level wildcard to match. The fifth, while the wildcard position and the topic portions after the wildcard matched, the preceding didn’t match.

Pretty simple so far. Here is where it gets crazy. You can have an arbitrary number of single level wildcards in a subscription. Here are some examples:

Subscription: /+/+/+/+ This one says: “Give me any publish whose topic is four sections deep. So /foo/bar/baz/quux and /spam/eggs/potato/biscut match, but /foo/bar/baz/quux/spam do not match.

Subscription: /Sports/+/Texas/+/Scores This one says, give me the scores of any sport in Texas. So, /Sports/Football/Texas/College/Scores matches. As does /Sports/Rivalries/Texas/Baylor/Scores. But /Sports/Texas/UTexas/events/tailgaiting does not.

I want to point out that there is no set way of structuring topics with regards to the information you’re trying to model, so when you decide upon your models, keep the wildcard subscribes in mind.

The second kind of wildcard has immensely simpler semantics. The multi-level wildcard: “#”. The multi-level wildcard subscribes to every topic that is on the same level or deeper in the hierarchy than the hash.

The simplest case is simply subscribing to “#”, which will deliver every single message published on any topic.

Let’s run through some examples: Our subscription topic is : /Sports/F1/#

Publish Number Publish Topic Receives
1 /Sports/F1/Circuit of the Americas
2 /Sports/Tennis/French Open/Winners
3 /Sports/F1/Hungarian Grand Prix/Accidents/Wheel Damage/Left/Front
4 /Sports/Tennis/US Open/Mixed Doubles/Winners

1 most certainly matches. It’s only one deeper. 2 does not match, we veer off at the Tennis subsection. 3 is incredibly specific and deep, but still matches due to our multi-level-wildcard. 4 Does not match, once again because of Tennis.

It’s important to note that a subscription topic like /Foo/#/Bar is invalid. Once a hash is in the subscription, that hash is the last element in that subscription.

Keep wildcard hashes in mind while modeling your security for MQTT. ClearBlade will have a solution to manage this in the coming future though, by providing full Read and Write ACL on arbitrary topic trees.