How to describe MQTT v5 user properties in an AsyncAPI document?

[damienklotz77]

Hi,

Our product has an asynchronous API in MQTT v5 protocol.
In this API, we have designed messages using MQTT v5 user properties.

We have described this API using an AsyncAPI v2.5.0 document.

Here is an minimalist example of how we have tried to describe these MQTT v5 user properties :

{
  "asyncapi": "2.5.0",
  "info": {
    "title": "mytitle",
    "version": "1.0.0"
  },
  "channels": {
    "mytopic": {
      "subscribe": {
        "message": {
          "headers": {
            "properties": {
              "myUserProperty": {
                "type": "string"
              }
            }
          },
          "payload": {
            "type": "string"
          }
        }
      }
    }
  }
}

When we use keyword “headers”, AsyncAPI studio requires the use of the “type” keyword with value “object” :

Headers schema type must be "object" ("headers" property must have required property "type").

According to MQTT v5 specification, user property is defined like following :

38 (0x26) Byte, Identifier of the User Property.
Followed by a UTF-8 String Pair.

https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901054

What is the correct way to describe MQTT v5 user properties in an AsyncAPI document ?

Thank you

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[fmvilas]

It should go into the MQTT5 binding. However, nobody has defined it yet. We do have the MQTT binding that's meant for versions prior to 5. Maybe you want to help contribute to the MQTT5 binding? Seems to me that it should go into the Server binding specifically.

[lmussier]

@fmvilas what is the difference in MQTT5 message properties and generic message header?
If one is defining MQTT5 binding (for that topic exclusively) don't you think it will ends up like asyncapi/bindings#158 ?

By the way since #158 seems to say generic header are a valid representation of key pair values, I guess the same goes for MQTT5.
There no need to define a particular way of representing those headers.

Does it make sense?

[fmvilas]

The difference is in the AsyncAPI specification. Message headers should contain application-specific stuff only and should leave protocol-specific stuff out. Everything that's related to a specific protocol, should go into a binding. Sure, you can put it in a header and that might work but we're trying to maintain a clear separation between the two.

Schema definition of the application headers. Schema MUST be of type "object". It MUST NOT define the protocol headers.

See https://www.asyncapi.com/docs/reference/specification/v2.5.0#messageObject.

Think about it this way: you should be able to use the same message definition with two different protocols. If you put protocol-specific stuff in the message.headers field, it would not make sense for the rest of the protocols.

In MQTT5, AFAIK, User Properties are for defining application-specific stuff so yeah, it should go on message headers when it makes sense. In my comment above, I thought these User Property fields were only present in the CONNECT package, that's why I said it should go in the MQTT5 Server Binding. Having a closer look at the spec, it seems there's also a User Property field for the PUBLISH package, which I'd say translates to our message somehow. So yeah, sorry for the confusion, if it's a User Property on the message, it should be a message header. If it's a User Property you're using when connecting to a broker, then it should go into the MQTT5 Server binding.

[lmussier]

Crystal clear, thank you @fmvilas for the extensive answer.