MQTT GUIDE
3 min readMQTT Payload Format Indicator and Content Type
The MQTT 5.0 Payload Format Indicator and Content Type are two optional PUBLISH properties that describe a message’s payload. The Payload Format Indicator is a single byte — 0 for an unspecified byte stream, 1 for UTF-8 text — and the Content Type is a free-form UTF-8 string, usually a MIME type such as application/json. Both travel with the message to every subscriber, so a receiver can tell how to read a payload without inspecting it.
An MQTT payload is just a blob of bytes — the protocol never cared what was inside. That works fine until a subscriber has to guess whether it received JSON, a protobuf, or a JPEG. MQTT 5.0 removes the guesswork with two optional descriptors a publisher can attach to a message.
How it works
When a client publishes, MQTT 5.0 lets it set two properties on the PUBLISH packet — and on a
Will message registered at connect. They describe the payload without changing it:
The indicator is a hint, not a contract
The Payload Format Indicator is advisory. The MQTT 5.0 spec lets a server that receives a payload marked UTF-8
but containing invalid UTF-8 reject it with reason code 0x99 (Payload format invalid), but that validation
is optional — most brokers simply forward the properties and the payload to subscribers as-is. The Content Type is never
interpreted by the broker at all; it is opaque metadata for the receiving application.
Payload format in TBMQ
TBMQ treats both descriptors as pass-through metadata: the Payload Format Indicator and Content Type a publisher sets are carried through to every subscriber unchanged — including across TBMQ's Kafka-backed message persistence — so your consumers can dispatch on them reliably. TBMQ does not reject a publish whose payload doesn't match its declared format; it delivers the message and its descriptors as sent. See the MQTT protocol guide for the full list of supported MQTT 5.0 features.
Frequently asked questions
What is the MQTT Payload Format Indicator?
A single-byte MQTT 5.0 property on a PUBLISH that says how to interpret the payload: 0 means an unspecified byte stream (the default), and 1 means the payload is UTF-8 encoded character data.
What is the Content Type property in MQTT 5.0?
An optional UTF-8 string a publisher attaches to describe the payload — usually a MIME type such as application/json. It is free-form: the broker forwards it to subscribers but does not interpret it.
Does the broker check that a payload marked UTF-8 really is UTF-8?
It may. The spec lets a server reject a mismatched payload with reason code 0x99 (Payload format invalid), but that validation is optional. Many brokers, including TBMQ, forward the properties and payload to subscribers unchanged.
Are these properties available in MQTT 3.1.1?
No. The Payload Format Indicator and Content Type are MQTT 5.0 features. In 3.1.1 you have to signal the payload type yourself — through the topic name, the payload, or an out-of-band convention.
Where can these properties appear?
On PUBLISH packets, and on a Will message defined in the CONNECT packet. They describe the application payload, so they do not apply to control packets like SUBSCRIBE.
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.