The default setting for the MQTT RETAIN flag is false, except for metadata messages published to the MetaDataQueueName as described in

The MQTT version 3.1.1 protocol does not support message headers. Any promoted field or additional fields defined on the WriterGroup or DataSetWriter other than RETAIN are not sent as MQTT message properties.

MQTT version 5.0 defines a number of standard message properties. These include properties explicitly defined in the MQTT specification, as well as the MQTT User Property which is a key-value pair of UTF-8 strings. The MQTT User Property is intended to provide a means of transferring application layer name-value tags whose meaning and interpretation are known only by the application programs responsible for sending and receiving them. They are used here to specify PubSub properties not directly supported by the MQTT protocol.

Table 167 describes how these properties shall be populated when a MQTT version 5.0 message is constructed.

Table 167 – OPC UA MQTT message properties

MQTT property name

MQTT property type

MQTT property value


User Property

Valid values are ua-data or ua-metadata.

Content Type


The MIME type for the message body.

The MIME types are specified in the message body subsections and

The MQTT message header shall include additional fields defined on the WriterGroup or DataSetWriter through the KeyValuePair array in the WriterGroupProperties and DataSetWriterProperties. The NamespaceIndex of the QualifiedName in the KeyValuePair shall be 0. The Name of the QualifiedName is constructed from a message prefix and the MQTT property name with the following syntax.

Name = message-<MQTT property name>

The Name of the key in the KeyValuePair shall have a prefix “message” followed by a hyphen and the MQTT property name.

Table 168 defines the MQTT standard message properties.

Table 168 – OPC UA MQTT standard message property configuration

MQTT property name

OPC UA DataTypes

MQTT data types




RETAIN bit in the header

Response Topic


UTF-8 Encoded String

Not available as message property for MQTT 3.1.1.

Correlation Data


Binary Data

Not available as message property for MQTT 3.1.1.

Message Expiry Interval


Four Byte Integer

Not available as message property for MQTT 3.1.1.

Content Type


UTF-8 Encoded String

Configuration option for the MIME.type of the message body for MQTT 3.1.1 and 5.0.

Not available as message property for MQTT 3.1.1.

Any name not in the Table 168 is assumed to be a MQTT User Property.

When a field is added to the header as a MQTT User Property the value is encoded as UTF-8 encoded String. If the value is not a String, then it is encoded using the non-reversible OPC UA JSON Data Encoding rules in OPC 10000-6. Promoted fields can only be sent for fields which are assumed to be a MQTT User Property and if the NetworkMessage contains only one DataSetMessage. The MQTT message header shall include additional promoted fields of the DataSet as a list of MQTT User Property name-value pairs. DataSet fields with the PromotedField flag set in the FieldMetaData fieldFlags are copied into the MQTT header. The FieldMetaData Structure is defined in For a UADP message mapping the promoted fields are also included in the UADP NetworkMessage. Promoted fields shall always be included in the header even if the DataSetMessage body is a delta frame and the DataSet field is not included in the delta frame. In this case the last known value is sent in the header.