Skip to content

Latest commit

 

History

History
184 lines (149 loc) · 7.23 KB

README.md

File metadata and controls

184 lines (149 loc) · 7.23 KB
Raw

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
servers:
  production:
    bindings:
      mqtt:
        clientId: guest
        cleanSession: true
        lastWill:
          topic: /last-wills
          qos: 2
          message: Guest gone offline.
          retain: false
        keepAlive: 60
        sessionExpiryInterval: 600
        maximumPacketSize: 1200
        bindingVersion: 0.2.0
servers:
  production:
    bindings:
      mqtt:
        sessionExpiryInterval:
          type: integer
          minimum: 30
          maximum: 1200
        maximumPacketSize:
          type: integer
          minimum: 256
        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
channels:
  user/signup:
    publish:
      bindings:
        mqtt:
          qos: 2
          retain: true
          messageExpiryInterval: 60
          bindingVersion: 0.2.0
channels:
  user/signup:
    publish:
      bindings:
        mqtt:
          messageExpiryInterval:
            type: integer
            minimum: 30
            maximum: 300
          bindingVersion: 0.2.0
channels:
  user/signup:
    subscribe:
      bindings:
        mqtt:
          qos: 2
          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
channels:
  user/signup:
    subscribe:
      message:
        bindings:
          mqtt:
            contentType: "application/json"
            correlationData:
              type: string
              format: uuid
            bindingVersion: 0.2.0
channels:
  userSignup:
    address: user/signup
    messages:
      userSignup:
        bindings:
          mqtt:
            payloadFormatIndicator: 1
            contentType: "application/json"
            correlationData:
              type: string
              format: uuid
            responseTopic:
              type: string
              pattern: "response/client/([a-z1-9]+)"
            bindingVersion: 0.2.0