Distinguish between protocol headers and application headers in runtime expressions

[GeraldLoeffler]

I'll use JMS as an example, but the same argument applies to Anypoint MQ and potentially other protocols.

A JMS message defines header, properties, and a body: https://javaee.github.io/javaee-spec/javadocs/javax/jms/Message.html . JMS uses different API calls to access headers and properties. JMS headers are equivalent to AsyncAPI protocol headers (i.e., a fixed set of well-known headers defined by the protocol (JMS)). By contrast, JMS properties are equivalent to AsyncAPI application headers (i.e., headers defined by the message sender to suit its needs).

In AsyncAPI, application headers are specified in the headers field of the message object. By contrast, protocol headers are specified in the message binding object, by convention in the headers field, as is the case for example in the HTTP bindings.

The correlationId field of the AsyncAPI message object uses runtime expressions to refer to headers. For example $message.header#/xyz refers to a header named xyz. But runtime expressions do not distinguish between application and protocol headers: both are designated by the header keyword in the runtime expression. This means that the runtime expression $message.header#/xyz cannot be translated into the appropriate JMS API calls without "knowing" that xyz is either a protocol header (JMS header) or an application header (JMS property).

There are 2 possible solutions:

1. In AsyncAPI runtime expressions distinguish between protocol headers and application headers. For example, use $message.header.protocol#/xyz for the former and $message.header#/xyz for the latter.
2. Alternatively, define header in runtime expressions in message objects to always mean application headers. And introduce runtime expressions to message binding objects (which deal with protocol-specifics) such that header there is defined to always mean protocol headers. For example, $message.header#/xyz in the message object (for example in the correlationId field) means the application header xyz. Conversely, $message.header#/xyz in the JMS message binding object (for example in a correlationId field to be introduced there) means the protocol header (JMS property) xyz.

[GeraldLoeffler]

Further on the 2 proposed solutions:

Solution 1. is simpler but means that the message object can only be used with one specific binding: only in this way correlationId (for example) in the message object can refer to protocol headers from that binding.

Solution 2. is more complex, and requires additional fields that use runtime expressions (such as correlationId) to be introduced to the message binding objects. But it has the advantage of clearly separating protocol-agnostic information (in the message object) from protocol-specific information (in the message binding object for a protocol). It therefore allows the same message object to be used with several bindings.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[fmvilas]

Yeah, I think it should go inside the bindings object (solution 2). The same protocol header might be different in each protocol. For instance, Content-Type for HTTP and contentType for MQTT.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[smoya]

Hi @GeraldLoeffler! It has been a while since you created this RFC-0. Do you wanna champion it?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: