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.01servers:
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.0Channel 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.01channels:
2 user/signup:
3 publish:
4 bindings:
5 mqtt:
6 messageExpiryInterval:
7 type: integer
8 minimum: 30
9 maximum: 300
10 bindingVersion: 0.2.01channels:
2 user/signup:
3 subscribe:
4 bindings:
5 mqtt:
6 qos: 2
7 bindingVersion: 0.2.0Message 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.01channels:
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