feat: add mqtt v5 specific bindings to mqtt (#201)

Co-authored-by: Sergio Moya <[email protected]>%0ACo-authored-by: Khuda Dad Nomani <[email protected]>%0ACo-authored-by: Lukasz Gornicki <[email protected]>
asyncapi · Dec 4, 2023 · e14c678 · e14c678
1 parent 36073fe
commit e14c678
Show file tree

Hide file tree

Showing 5 changed files with 206 additions and 36 deletions.
diff --git a/mqtt/README.md b/mqtt/README.md
@@ -2,11 +2,13 @@
 
 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.
+
 <a name="version"></a>
 
 ## Version
 
-Current version is `0.1.0`.
+Current version is `0.2.0`.
 
 
 <a name="server"></a>
@@ -17,21 +19,23 @@ This object contains information about the server representation in MQTT.
 
 ##### Fixed Fields
 
-Field Name | Type | Description
----|:---:|---
-<a name="serverBindingObjectClientId"></a>`clientId` | string | The client identifier.
-<a name="serverBindingObjectCleanSession"></a>`cleanSession` | boolean | Whether to create a persistent connection or not. When `false`, the connection will be persistent.
-<a name="serverBindingObjectLastWill"></a>`lastWill` | object | Last Will and Testament configuration.
-<a name="serverBindingObjectLastWillTopic"></a>`lastWill.topic` | string | The topic where the Last Will and Testament message will be sent.
-<a name="serverBindingObjectLastWillQoS"></a>`lastWill.qos` | integer | 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.
-<a name="serverBindingObjectLastWillMessage"></a>`lastWill.message` | string | Last Will message.
-<a name="serverBindingObjectLastWillRetain"></a>`lastWill.retain` | boolean | Whether the broker should retain the Last Will and Testament message or not.
-<a name="serverBindingObjectKeepAlive"></a>`keepAlive` | integer | Interval in seconds of the longest period of time the broker and the client can endure without sending a message.
-<a name="serverBindingObjectBindingVersion"></a>`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed.
+Field Name | Type | MQTT Versions | Description
+---|:---:|:---:|---|
+<a name="serverBindingObjectClientId"></a>`clientId` | string | 3, 5 | The client identifier.
+<a name="serverBindingObjectCleanSession"></a>`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.
+<a name="serverBindingObjectLastWill"></a>`lastWill` | object | 3, 5 | Last Will and Testament configuration. `topic`, `qos`, `message` and `retain` are properties of this object as shown below.
+<a name="serverBindingObjectLastWillTopic"></a>`lastWill.topic` | string | 3, 5 | The topic where the Last Will and Testament message will be sent.
+<a name="serverBindingObjectLastWillQoS"></a>`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.
+<a name="serverBindingObjectLastWillMessage"></a>`lastWill.message` | string | 3, 5 | Last Will message.
+<a name="serverBindingObjectLastWillRetain"></a>`lastWill.retain` | boolean | 3, 5 | Whether the broker should retain the Last Will and Testament message or not.
+<a name="serverBindingObjectKeepAlive"></a>`keepAlive` | integer | 3, 5 | Interval in seconds of the longest period of time the broker and the client can endure without sending a message.
+<a name="serverBindingObjectSessionExpiryInterval"></a>`sessionExpiryInterval` | integer \| [Schema Object][schemaObject] \| [Reference Object](referenceObject) | 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.
+<a name="serverBindingObjectMaximumPacketSize"></a>`maximumPacketSize` | integer \| [Schema Object][schemaObject] \| [Reference Object](referenceObject) | 5 | Number of bytes or a *Schema Object* representing the maximum packet size the client is willing to accept.
+<a name="serverBindingObjectBindingVersion"></a>`bindingVersion` | string | | The version of this binding. If omitted, "latest" MUST be assumed. |
 
 This object MUST contain only the properties defined above.
 
-##### Example
+##### Examples
 
 ```yaml
 servers:
@@ -46,9 +50,24 @@ servers:
           message: Guest gone offline.
           retain: false
         keepAlive: 60
-        bindingVersion: 0.1.0
+        sessionExpiryInterval: 600
+        maximumPacketSize: 1200
+        bindingVersion: 0.2.0
+```
+```yaml
+servers:
+  production:
+    bindings:
+      mqtt:
+        sessionExpiryInterval:
+          type: integer
+          minimum: 30
+          maximum: 1200
+        maximumPacketSize:
+          type: integer
+          minimum: 256
+        bindingVersion: 0.2.0
 ```
-
 
 <a name="channel"></a>
 
@@ -57,7 +76,6 @@ servers:
 This object MUST NOT contain any properties. Its name is reserved for future use.
 
 
-
 <a name="operation"></a>
 
 ## Operation Binding Object
@@ -66,15 +84,16 @@ This object contains information about the operation representation in MQTT.
 
 ##### Fixed Fields
 
-Field Name | Type | Applies To | Description
----|:---:|:---:|---
-<a name="operationBindingObjectQoS"></a>`qos` | integer | Publish, Subscribe | 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).
-<a name="operationBindingObjectRetain"></a>`retain` | boolean | Publish, Subscribe | Whether the broker should retain the message or not.
-<a name="operationBindingObjectBindingVersion"></a>`bindingVersion` | string | Publish, Subscribe | The version of this binding. If omitted, "latest" MUST be assumed.
+Field Name | Type | Applies To | MQTT Versions | Description
+---|:---:|:---:|:---:|---
+<a name="operationBindingObjectQoS"></a>`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).
+<a name="operationBindingObjectRetain"></a>`retain` | boolean | Publish | 3, 5 | Whether the broker should retain the message or not.
+<a name="operationBindingObjectMessageExpiryInterval"></a>`messageExpiryInterval`  | integer \| [Schema Object][schemaObject] \| [Reference Object](referenceObject)| Publish | 5 | Interval in seconds or a *Schema Object* containing the definition of the lifetime of the message. 
+<a name="operationBindingObjectBindingVersion"></a>`bindingVersion` | string |  | |  The version of this binding. If omitted, "latest" MUST be assumed.
 
 This object MUST contain only the properties defined above.
 
-##### Example
+##### Examples
 
 ```yaml
 channels:
@@ -84,9 +103,30 @@ channels:
         mqtt:
           qos: 2
           retain: true
-          bindingVersion: 0.1.0
+          messageExpiryInterval: 60
+          bindingVersion: 0.2.0
+```
+```yaml
+channels:
+  user/signup:
+    publish:
+      bindings:
+        mqtt:
+          messageExpiryInterval:
+            type: integer
+            minimum: 30
+            maximum: 300
+          bindingVersion: 0.2.0
+```
+```yaml
+channels:
+  user/signup:
+    subscribe:
+      bindings:
+        mqtt:
+          qos: 2
+          bindingVersion: 0.2.0
 ```
-
 
 <a name="message"></a>
 
@@ -96,18 +136,48 @@ This object contains information about the message representation in MQTT.
 
 ##### Fixed Fields
 
-Field Name | Type | Description
----|:---:|---
-<a name="messageBindingObjectBindingVersion"></a>`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed.
+Field Name | Type | MQTT Versions | Description
+---|:---:|:---:|---
+<a name="messageBindingObjectPayloadFormatIndicator"></a>`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. |
+<a name="messageBindingObjectCorrelationData"></a>`correlationData` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | 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.
+<a name="messageBindingObjectContentType"></a>`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.
+<a name="messageBindingObjectResponseTopic"></a>`responseTopic` | URI string \| [Schema Object][schemaObject] \| [Reference Object](referenceObject) | 5 | The topic (channel URI) for a response message.
+<a name="messageBindingObjectBindingVersion"></a>`bindingVersion` | string | | The version of this binding. If omitted, "latest" MUST be assumed.
 
 This object MUST contain only the properties defined above.
 
+##### Examples
+
+```yaml
+channels:
+  user/signup:
+    subscribe:
+      message:
+        bindings:
+          mqtt:
+            contentType: "application/json"
+            correlationData:
+              type: string
+              format: uuid
+            bindingVersion: 0.2.0
+```
 ```yaml
 channels:
   user/signup:
     publish:
       message:
         bindings:
           mqtt:
-            bindingVersion: 0.1.0
+            payloadFormatIndicator: 1
+            contentType: "application/json"
+            correlationData:
+              type: string
+              format: uuid
+            responseTopic:
+              type: string
+              pattern: "response/client/([a-z1-9]+)"
+            bindingVersion: 0.2.0
 ```
+
+[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject
+[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject
diff --git a/mqtt/json_schemas/message.json b/mqtt/json_schemas/message.json
@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/bindings/mqtt/message.json",
-  "title": "Operation Schema",
+  "title": "Message Schema",
   "description": "This object contains information about the message representation in MQTT.",
   "type": "object",
   "additionalProperties": false,
@@ -11,17 +11,64 @@
     }
   },
   "properties": {
+    "payloadFormatIndicator": {
+      "type": "integer",
+      "enum": [0, 1],
+      "description": "1 indicates that the payload is UTF-8 encoded character data.  0 indicates that the payload format is unspecified.",
+      "default": 0
+    },
+    "correlationData": {
+      "oneOf": [
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/schema.json"
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/Reference.json"
+        }
+      ],
+      "description": "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": {
+      "type": "string",
+      "description": "String describing the content type of the message payload. This should not conflict with the contentType field of the associated AsyncAPI Message object."
+    },
+    "responseTopic": {
+      "oneOf": [
+        {
+          "type": "string",
+          "format": "uri-template",
+          "minLength": 1
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/schema.json"
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/Reference.json"
+        }
+      ],
+      "description": "The topic (channel URI) to be used for a response message."
+    },
+
     "bindingVersion": {
       "type": "string",
       "enum": [
-        "0.1.0"
+        "0.2.0"
       ],
       "description": "The version of this binding. If omitted, 'latest' MUST be assumed."
     }
   },
   "examples": [
     {
-      "bindingVersion": "0.1.0"
+      "bindingVersion": "0.2.0"
+    },
+    {
+      "contentType": "application/json",
+      "correlationData": {
+        "type": "string",
+        "format": "uuid"
+      },
+      "responseTopic": "application/responses",
+      "bindingVersion": "0.2.0"
     }
   ]
 }
diff --git a/mqtt/json_schemas/operation.json b/mqtt/json_schemas/operation.json
@@ -13,16 +13,33 @@
   "properties": {
     "qos": {
       "type": "integer",
+      "enum": [0,1,2],
       "description": "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": {
       "type": "boolean",
       "description": "Whether the broker should retain the message or not."
     },
+    "messageExpiryInterval": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/schema.json"
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/Reference.json"
+        }
+      ],
+      "description": "Lifetime of the message in seconds"
+    },
     "bindingVersion": {
       "type": "string",
       "enum": [
-        "0.1.0"
+        "0.2.0"
       ],
       "description": "The version of this binding. If omitted, 'latest' MUST be assumed."
     }
@@ -31,7 +48,8 @@
     {
       "qos": 2,
       "retain": true,
-      "bindingVersion": "0.1.0"
+      "messageExpiryInterval": 60,
+      "bindingVersion": "0.2.0"
     }
   ]
 }
diff --git a/mqtt/json_schemas/server.json b/mqtt/json_schemas/server.json
@@ -18,7 +18,7 @@
     },
     "cleanSession": {
       "type": "boolean",
-      "description": "Whether to create a persistent connection or not. When 'false', the connection will be persistent."
+      "description": "Whether to create a persistent connection or not. When 'false', the connection will be persistent. This is called clean start in MQTTv5."
     },
     "lastWill": {
       "type": "object",
@@ -47,10 +47,41 @@
       "type": "integer",
       "description": "Interval in seconds of the longest period of time the broker and the client can endure without sending a message."
     },
+    "sessionExpiryInterval": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 0
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/schema.json"
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/Reference.json"
+        }
+      ],
+      "description": "Interval time 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": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 4294967295
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/schema.json"
+        },
+        {
+          "$ref": "https://asyncapi.com/definitions/2.6.0/Reference.json"
+        }
+      ],
+      "description": "Number of bytes or a Schema Object representing the Maximum Packet Size the Client is willing to accept."
+    },
     "bindingVersion": {
       "type": "string",
       "enum": [
-        "0.1.0"
+        "0.2.0"
       ],
       "description": "The version of this binding. If omitted, 'latest' MUST be assumed."
     }
@@ -66,7 +97,9 @@
         "retain": false
       },
       "keepAlive": 60,
-      "bindingVersion": "0.1.0"
+      "sessionExpiryInterval": 120,
+      "maximumPacketSize": 1024,
+      "bindingVersion": "0.2.0"
     }
   ]
 }
diff --git a/mqtt5/README.md b/mqtt5/README.md
@@ -2,6 +2,8 @@
 
 This document defines how to describe MQTT 5-specific information on AsyncAPI.
 
+# **Deprecation Warning**: MQTT version 5 specific bindings are deprecated in favor of [MQTT bindings](../mqtt/README.md) that are not version specific.
+
 <a name="version"></a>
 
 ## Version