MQTT Bindings

This document defines how to describe MQTT-specific information on AsyncAPI.

It applies to all versions of MQTT, although specific binding fields may only apply to particular versions.

Version

Current version is 0.2.0.

Server Binding Object

This object contains information about the server representation in MQTT.

Fixed Fields

Field Name	Type	MQTT Versions	Description
`clientId`	string	3, 5	The client identifier.
`cleanSession`	boolean	3, 5	Whether to create a persistent connection or not. When `false`, the connection will be persistent. This is called clean start in MQTTv5.
`lastWill`	object	3, 5	Last Will and Testament configuration. `topic`, `qos`, `message` and `retain` are properties of this object as shown below.
`lastWill.topic`	string	3, 5	The topic where the Last Will and Testament message will be sent.
`lastWill.qos`	integer	3, 5	Defines how hard the broker/client will try to ensure that the Last Will and Testament message is received. Its value MUST be either 0, 1 or 2.
`lastWill.message`	string	3, 5	Last Will message.
`lastWill.retain`	boolean	3, 5	Whether the broker should retain the Last Will and Testament message or not.
`keepAlive`	integer	3, 5	Interval in seconds of the longest period of time the broker and the client can endure without sending a message.
`sessionExpiryInterval`	integer \| Schema Object \| Reference Object	5	Interval in seconds or a Schema Object containing the definition of the interval. The broker maintains a session for a disconnected client until this interval expires.
`maximumPacketSize`	integer \| Schema Object \| Reference Object	5	Number of bytes or a Schema Object representing the maximum packet size the client is willing to accept.
`bindingVersion`	string		The version of this binding. If omitted, "latest" MUST be assumed.

This object MUST contain only the properties defined above.

Examples

1servers:
2  production:
3    bindings:
4      mqtt:
5        clientId: guest
6        cleanSession: true
7        lastWill:
8          topic: /last-wills
9          qos: 2
10          message: Guest gone offline.
11          retain: false
12        keepAlive: 60
13        sessionExpiryInterval: 600
14        maximumPacketSize: 1200
15        bindingVersion: 0.2.0

1servers:
2  production:
3    bindings:
4      mqtt:
5        sessionExpiryInterval:
6          type: integer
7          minimum: 30
8          maximum: 1200
9        maximumPacketSize:
10          type: integer
11          minimum: 256
12        bindingVersion: 0.2.0

Channel Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Operation Binding Object

This object contains information about the operation representation in MQTT.

Fixed Fields

Field Name	Type	Applies To	MQTT Versions	Description
`qos`	integer	Publish, Subscribe	3, 5	Defines the Quality of Service (QoS) levels for the message flow between client and server. Its value MUST be either 0 (At most once delivery), 1 (At least once delivery), or 2 (Exactly once delivery).
`retain`	boolean	Publish	3, 5	Whether the broker should retain the message or not.
`messageExpiryInterval`	integer \| Schema Object \| Reference Object	Publish	5	Interval in seconds or a Schema Object containing the definition of the lifetime of the message.
`bindingVersion`	string			The version of this binding. If omitted, "latest" MUST be assumed.

This object MUST contain only the properties defined above.

Examples

1channels:
2  user/signup:
3    publish:
4      bindings:
5        mqtt:
6          qos: 2
7          retain: true
8          messageExpiryInterval: 60
9          bindingVersion: 0.2.0

1channels:
2  user/signup:
3    publish:
4      bindings:
5        mqtt:
6          messageExpiryInterval:
7            type: integer
8            minimum: 30
9            maximum: 300
10          bindingVersion: 0.2.0

1channels:
2  user/signup:
3    subscribe:
4      bindings:
5        mqtt:
6          qos: 2
7          bindingVersion: 0.2.0

Message Binding Object

This object contains information about the message representation in MQTT.

Fixed Fields

Field Name	Type	MQTT Versions	Description
`payloadFormatIndicator`	integer	5	Either: 0 (zero): Indicates that the payload is unspecified bytes, or 1: Indicates that the payload is UTF-8 encoded character data.
`correlationData`	Schema Object \| Reference Object	5	Correlation Data is used by the sender of the request message to identify which request the response message is for when it is received.
`contentType`	string	5	String describing the content type of the message payload. This should not conflict with the `contentType` field of the associated AsyncAPI Message object.
`responseTopic`	URI string \| Schema Object \| Reference Object	5	The topic (channel URI) for a response message.
`bindingVersion`	string		The version of this binding. If omitted, "latest" MUST be assumed.

This object MUST contain only the properties defined above.

Examples

1channels:
2  user/signup:
3    subscribe:
4      message:
5        bindings:
6          mqtt:
7            contentType: "application/json"
8            correlationData:
9              type: string
10              format: uuid
11            bindingVersion: 0.2.0

1channels:
2  userSignup:
3    address: user/signup
4    messages:
5      userSignup:
6        bindings:
7          mqtt:
8            payloadFormatIndicator: 1
9            contentType: "application/json"
10            correlationData:
11              type: string
12              format: uuid
13            responseTopic:
14              type: string
15              pattern: "response/client/([a-z1-9]+)"
16            bindingVersion: 0.2.0

On this page

mqtt

MQTT Bindings

Version

Server Binding Object

Fixed Fields

Examples

Channel Binding Object

Operation Binding Object

Fixed Fields

Examples

Message Binding Object

Fixed Fields

Examples