Support defining and referencing protocol headers

[GeraldLoeffler]

The definitions in the spec of the Message Object and Message Bindings Object currently do not provide a standardised way to define protocol headers or to refer to protocol headers (for example from the correlationId field in the message object). This leads to contradictory message bindings definitions and to message object definitions that are implicitly dependent on the binding being used.

Typical examples for this are correlation ID and message ID and how they are transmitted in messages and referred to from an AsyncAPI document:

In this MQTT example, CorrelId is treated as an application header. But it's location is specified as MQMD/CorrelId in the message object (not the message binding object). This makes the message object specific to MQTT, and not applicable to other protocols. For example, the same message object could not be used with JMS, because in JMS the correlation ID is a protocol header (JMSCorrelationID), and it is not possible to refer to protocol headers from the message object. As another example, in HTTP correlation ID is conventionally passed as the x-correlation-id (application or protocol?) header, so the MQMD/CorrelId definition is not applicable to HTTP. The spec currently does not support writing a message object that defines the usage of correlation ID for MQTT and JMS and/or HTTP. Specifically, there is no way to express that JMSCorrelationID is a protocol header in JMS and refer to it from the message object.

Another example relates to Message IDs: For example, in JMS one common pattern is for the sender to send two protocol headers JMSMessageID and JMSReplyTo, and for the recipient to send response messages to the destination specified by JMSReplyTo in the request message, with JMSCorrelationID in the response message set to the value of JMSMessageID in the request message. All of these are protocol headers in JMS. AsyncAPI does not currently allow the definition of a message object (with or without binding objects) that can describe this situation.

The way message objects and message bindings objects are defined in the spec has resulted in incompatible message bindings object definitions:

• The HTTP Message Binding Object defines protocol headers through a Schema object. (Which makes this example from the spec repo invalid).
• The AMQP bindings definitions define, for example, replyTo (in the operation binding object, not the message binding object) as a fixed string field (not a Schema object), although it would typically be set dynamically in each request message (as in the above example).
• The IBM MQ message binding object defines protocol headers as a comma-separated string.

Also note that the approach taken by the HTTP message binding requires most AsyncAPI docs to define schema objects for the common HTTP protocol headers, although they are known in advance and common. Instead, protocol header schema objects should be part of the bindings specification.

In summary, the AsyncAPI spec should be extended with a standardised way

• for message binding objects to define protocol headers
• for message objects to refer to protocol headers, for example from the correlationId field in the message object
• for bindings specifications to provide schema objects for standard protocol headers

[GeraldLoeffler]

This is not an RFC at stage 1, and i did not add that label (at least not consciously).

[GeraldLoeffler]

asyncapi/bindings#64 captures the problem with the current AMQP bindings spec regarding protocol headers.

[GeraldLoeffler]

#555 captures the need for bindings specs to provide schema objects for protocol headers.

[GeraldLoeffler]

asyncapi/bindings#62 already existed and captures the need for guidance and conventions for defining bindings specs.

[GeraldLoeffler]

#556 captures the need for runtime expressions to make it clear whether they are referring to a protocol header or an application header.

[GeraldLoeffler]

#557 captures the need to support not only correlationId but also messageId, replyTo, and the like.

[GeraldLoeffler]

#558 captures the need to support message exchange patterns such as request-reply in AsyncAPI.

[GeraldLoeffler]

As discussed in the SIG meeting on the 8th of June 2021 i have now submitted individual issues (see above) for the different parts of this umbrella-issue. I am therefore closing this issue.