HiveMQ Logo
Payload Format Description - MQTT 5 Essentials Part 8

Payload Format Description - MQTT 5 Essentials Part 8

author portrait

Written by Florian Raschbichler

Category: MQTT 5 MQTT 5 Essentials HiveMQ IoT

Published: November 12, 2019

In the MQTT 5 Essentials, we explore the foundational changes that MQTT 5 introduces and the top reasons MQTT users make the move to MQTT v5. Our goal is to individually examine each of the new features in the MQTT 5 protocol. Today, we’ll continue with another groundbreaking set of features: Payload Format Indicators and Content Types.

At the end of this blog post, we have a video on the same topic that complements this blog post.

Modern IoT projects are often big and complex. These large-scale projects usually require the collaboration of multiple vendors and teams. Since MQTT is the de facto standard protocol for IoT, improved interoperability and transparency across systems topped the list of user requirements for MQTT version 5.

Today’s features aim to meet those user requirements.

Payload Format Indicator

The Payload Format Indicator is part of any MQTT packet that can contain a payload. Specifically, a CONNECT packet that contains a WILL message or a PUBLISH packet. The indicator is an optional byte value. A value of 0 indicates an “unspecified byte stream”. A value of 1 indicates a “UTF-8 encoded payload”. If no Payload Format Indicator is provided, the default value is 0.

CONNECT packet with Payload Format Description
The Payload Format Description is optional, it can have the values "1" or "0".

Content Type

Similar to the Payload Format Indicator, the Content Type is optional and can be part of a CONNECT that contains a WILL message or of any PUBLISH. The Content Type must be a UTF-8 encoded string. The Content Type value identifies the kind of UTF-8 encoded payload. When the Payload Format Indicator is set to 1, a MIME content type descriptor is expected (but not mandatory). Any valid UTF-8 String can be used.

CONNECT packet with Content Type
For UTF-8 encoded strings Content Types can be defined.

Why describe the payload format?

You can use a combination of the Payload Format Indicator and Content Type to transparently describe the payload content of any application message. This feature opens up the possibility to create and define industry-wide standards for MQTT with variable payload formats. Experts such as Ian Skerrett see this sort of standardization as a natural next step in the rise of the MQTT protocol.

Pre-parsing with Payload Format Description
Payload Format Description allows pre-parsing without the need to open the payload

When looking at individual deployments, payload content description in the headers can be really helpful. This information insures correct processing of each message without the need to look inside the actual payload. Based on the exact type of content, individual messages in a system can require different kinds of parsing. In some cases, the persistence of messages is dependant upon the exact type of payload the message contains. Since the specific content-type definitions are subject to user design, the potential applications of this feature are seemingly limitless.


  • The Payload Format Indicator defines whether a payload is an undefined array of bytes or an UTF-8 encoded message.
  • In the case of UTF-8 encoded messages, the sender can use the content type to define the specifics of the payload.
  • These two features open the door to transparent definition of payload content across large systems and, potentially, entire industries.
  • As pre-parsing actual payloads becomes obsolete, telegraphing the proper message processing can have a significant positive impact on scalability.
  • While it is expected that most users rely on known MIME types to describe content, arbitrary UTF-8 Strings can be used.

Are you using payload format description or thinking of a specific use case for these features? We’d love to hear about it in the comments!

Learn everything about MQTT v5

Over the next few weeks, we will continue our technical deep dive into all of the MQTT 5 features. In Part 9 of this series we will be talking about Request - Response Pattern. If you would like to get regular updates and don’t want to miss a post, sign up for our newsletter. Do check out MQTT Glossary to know all the key MQTT terminologies.

author Florian Raschbichler

About Florian Raschbichler

Florian serves as the head of the HiveMQ support team with years of first hand experience overcoming challenges in achieving reliable, scalable, and secure IoT messaging for enterprise customers.
mail icon Contact Florian

newer posts The HiveMQ MQTT Client 1.1.3 is released
Shared Subscriptions - MQTT 5 Essentials Part 7 older posts