What Is the MQTT Payload Format Indicator and Content Type?
These two MQTT 5 properties let a message describe its own body: whether it is text or binary, and what type of content it holds. For a mixed telemetry system carrying JSON from some devices and protobuf from others, they let a consumer choose the right parser from the header instead of sniffing the payload. This page explains what each property means and how they cooperate.
MQTT Payload Format and Content Type in one line: The MQTT payload format indicator is an MQTT 5 property that flags a message payload as either unspecified bytes or as UTF-8 text. The content type is a separate property carrying a free-form MIME type string, such as application/json, that names the format of the body. Together they let a subscriber select the correct parser from the message header rather than inspecting the payload itself.
What Each Property Declares
The payload format indicator is deliberately coarse: it says either that the payload is arbitrary binary data or that it is a UTF-8 encoded character string. That single bit lets a broker or a consumer know whether it is even meaningful to treat the body as text. A broker that receives a message claiming UTF-8 but containing invalid byte sequences is entitled to reject it, which catches a class of encoding bugs at the boundary rather than deep in a downstream parser.
The content type property is the finer description. It is a free-form string intended to hold a MIME type, so a JSON document is labelled application/json, and other formats carry their own conventional types. MQTT does not enforce any particular vocabulary or validate the string; it simply carries it from publisher to subscriber. The meaning is a contract between the applications at each end, in the same spirit as a JSON payload schema that both sides agree to honour.
The two properties complement each other rather than duplicate. The format indicator answers is this text at all, cheaply and definitively. The content type answers if I am going to parse it, what grammar do I use. A message could be flagged as UTF-8 text with content type application/json, or as binary with a content type naming a protobuf-encoded format. Neither property changes the bytes; they annotate them so the receiver does not have to guess.
Where They Help and Where Sparkplug Differs
In a heterogeneous telemetry fleet these properties earn their keep. If some gateways publish JSON and others publish a binary format, a single ingestion service subscribing across the fleet can read the content type and dispatch each message to the correct decoder without a fragile heuristic like peeking at the first byte. That makes the ingestion path both faster and more robust, which matters when it feeds a time-series database that must not choke on an unexpected format.
Sparkplug is the notable exception, and it is worth being explicit. Sparkplug B fixes its payload format by definition: every Sparkplug message is a protobuf-encoded payload of a defined structure, so a Sparkplug consumer already knows the format from the topic namespace and does not rely on the content type to choose a parser. In a pure Sparkplug system these annotation properties add little. They shine in plain-MQTT designs where payload formats genuinely vary, which is one axis of the plain MQTT versus Sparkplug decision.
As with all header metadata, there is a small cost. A content type string rides on every message that carries it, so on a high-rate publisher over a metered link the sensible pattern is to send the format description where it is stable and not to restamp an unchanging content type onto every single reading if the topic already implies the format. The properties are a tool for clarity at boundaries, not something to sprinkle on every packet without thought.
Frequently Asked Questions
Can a broker reject a payload that lies about its format?
Yes, for the UTF-8 case. If a publisher sets the payload format indicator to text but the payload contains byte sequences that are not valid UTF-8, an MQTT 5 broker is permitted to treat that as a protocol error and refuse the message. This lets encoding mistakes be caught right at the broker boundary instead of failing obscurely in a downstream consumer. The content type string itself is not validated by the broker, since it is free-form and meaningful only to the applications.
Do I need these properties if I use Sparkplug B?
Generally no. Sparkplug B defines a single fixed payload encoding, a protobuf structure, so a Sparkplug consumer already knows the format from the fact that the message is on a Sparkplug topic and does not need the content type to select a parser. These properties are most useful in plain-MQTT systems where different devices publish different formats such as JSON and binary, and a consumer needs a header-level hint to route each message to the right decoder.
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.