What Is an MQTT User Property?
A user property is MQTT 5's answer to a question every integrator eventually asks: how do I attach a little metadata to a message without polluting the payload? For controls work it is a clean way to carry units, a source tag, or a schema version alongside a reading. This page explains what a user property is, how it rides in the packet, and where it helps and where it does not.
MQTT User Property in one line: An MQTT user property is a custom key-value string pair, added in MQTT 5, that a publisher or subscriber can attach to a packet header. You may include as many as you like on a single message, keys can repeat, and the broker passes them through untouched. It lets applications carry metadata such as units, a source identifier, or a content version outside the message payload.
How a User Property Rides in the Packet
A user property is a UTF-8 key and a UTF-8 value placed in the properties section of an MQTT 5 control packet. It is part of the MQTT 5 properties mechanism, the same header area that carries things like the message expiry interval and the content type. Unlike those defined properties, a user property has no meaning to MQTT itself; the specification reserves it entirely for applications. The broker's only obligation is to forward user properties on a PUBLISH from publisher to subscriber unchanged.
You can attach more than one user property to a single message, and the same key may appear multiple times, so the collection is best thought of as an ordered list of pairs rather than a strict map. This matters if you use a repeated key to represent, for example, a list of tags. The ordering the sender used is preserved, so an application that cares about order can rely on it. On packets other than PUBLISH, such as CONNECT or SUBSCRIBE, user properties are also allowed and are similarly application-defined between client and broker.
Because user properties are separate from the payload, they are readable by middleware that does not want to parse the body. A router or bridge can inspect a user property to make a decision without deserializing a binary Sparkplug payload or a JSON document. That separation is the whole appeal: metadata that describes the message lives in the header, and the actual data lives in the payload, and the two can evolve independently.
Where User Properties Help in SCADA Telemetry
The natural uses are the small facts that describe a reading without being the reading. Units are a classic example: publishing a numeric value and carrying its engineering unit as a user property lets a consumer render or validate it without a lookup. A source or gateway identifier as a user property lets an ingestion service know where a message originated even after it has passed through a bridge. A content or schema version as a user property lets a consumer pick the right parser, which pairs well with a schema registry.
There is an important boundary with Sparkplug. Sparkplug B defines its own self-describing payload, where metrics carry their names, datatypes, and metadata inside the protobuf body, so a well-formed Sparkplug system does not need user properties to convey that information and generally does not use them for it. User properties are more at home in a plain-MQTT or a JSON payload design where you want header-level metadata without inventing your own envelope. Knowing which world you are in keeps you from adding redundant metadata.
A caution worth stating: user properties add bytes to every message that carries them, and on a metered cellular telemetry link those bytes are not free. A short units string repeated on every one-second publish adds up. The efficient pattern is to send descriptive metadata once, on connect or on a birth message, and let the steady stream of data messages stay lean, rather than stamping the same units onto every single reading. This is the same overhead discipline that makes people reach for aliases in the first place.
Frequently Asked Questions
Does the broker do anything with a user property?
Almost nothing. On a PUBLISH, the broker is required to forward all user properties to subscribers unchanged, and it must not reorder or alter them. It does not interpret them, index on them, or filter by them. Any meaning a user property carries is entirely between the applications at each end. If you want the broker to route or filter based on metadata, that decision belongs in the topic hierarchy, not in a user property, because topics are what the broker actually matches against.
Can I put many user properties on one message?
Yes. A single MQTT 5 packet may carry multiple user properties, and keys are allowed to repeat, so you can attach several pieces of metadata or even a repeated key representing a list. The order the sender used is preserved end to end. The only practical limit is the maximum packet size negotiated for the connection and, on a metered link, your own tolerance for the extra bytes on every message that carries them.
Sources and verification
This page references the protocol specifications published by the organizations below. Editions, product capabilities, and documentation change over time - confirm current requirements and specifications directly with the source.
- MQTT Version 5.0 (OASIS Standard) - OASIS (v5.0, 2019)
Merobix is not affiliated with, endorsed by, or sponsored by these organizations; their names are used only to identify the standards and products discussed.
Automation services
Need help turning this into a working system?
Merobix integrates SCADA, programs Allen-Bradley and Siemens PLCs, and designs and fabricates industrial control panels.
Meeting requests are reviewed before confirmation.