MQTT GUIDE
3 min readMQTT User Properties
User Properties are arbitrary UTF-8 key–value pairs you can attach to MQTT 5.0 packets — the MQTT equivalent of custom HTTP headers. They travel with the message and let you carry metadata such as a content type, tenant ID, or tracing token without encoding it into the topic or payload.
Sometimes a message needs to carry a little metadata — what kind of message it is, which tenant it belongs to, a trace ID for debugging. Before MQTT 5.0 you had to smuggle that into the topic or the payload. User Properties give you a proper place to put it.
Custom headers for MQTT
User Properties are arbitrary UTF-8 key–value pairs attached to a packet — the MQTT equivalent of custom HTTP headers. They ride alongside the message from publisher to subscriber, so a consumer can branch on them without the publisher having to bake the information into the topic name or the message body.
Good uses for user properties
User properties in TBMQ
TBMQ passes User Properties through end to end, from the publishing client to every subscriber, untouched — so you can rely on them for routing hints and metadata. It's the same pass-through the broker gives the other MQTT 5.0 message metadata: the request-response properties and the payload format and content type. See the MQTT protocol guide for supported 5.0 features.
Frequently asked questions
What are MQTT user properties?
Arbitrary UTF-8 key–value pairs you can attach to MQTT 5.0 packets, most usefully to a PUBLISH. They work like custom HTTP headers: application metadata that travels with the message without being part of the topic or payload.
Can I use the same key more than once?
Yes. User properties are an ordered list of name–value pairs, and the same name may appear multiple times. Order is preserved, so a receiver sees them exactly as the sender set them.
What should I use user properties for?
Metadata that helps route or interpret a message: a message type or schema version, a tenant or device ID, a content type, or a tracing/correlation token. Keeping it in properties avoids overloading the topic string or parsing it out of the payload.
Do user properties work in MQTT 3.1.1?
No. User properties are an MQTT 5.0 feature. In 3.1.1 you have to encode metadata into the topic or the payload yourself.
Does the broker read or change user properties?
It shouldn’t. The broker forwards them with the message. A compliant broker delivers the same user properties the publisher set (some brokers may add their own, but they don’t alter yours).
Run it yourself
TBMQ is a free, open-source MQTT broker built to scale. Spin it up in minutes or try the live demo — no install required.