Introduction

This proposal is to add a version field into the message object. This is to allow a more granular versioning.

Problem Statement

Currently, versioning in AsyncAPI is done at the application level. This inherently implies that all messages are of the same version, or that events do not hold a version at all. This approach works when an application fully controls its specifications/messages, with no cross references from other applications. An example are openAPI specs.

However, in environments with continuous development and/or fast iterations, application level versioning looses its benefit. Versioning becomes more important at the message level. Without granular versioning, any change in the application version applies to all messages it sends and receives, which can be problematic as shown in the example.

Example

Payment-service (v1.0.0) receives [billing-agreement-created...], sends [payment-success].
Comms-service (v1.0.0) receives [payment-success, payment-failed, billing-agreement-created, address-changed..] sends [communication-send...]

All the events received and sent are then version 1.0.0.

If the communication-send message needs a new field (e.g., adding SMS as a type), the comms-service would become v1.1.0, and all its messages would then be version 1.1.0.

This change would require updating all other AsyncAPI files for payment-service and others, as the comms-service would be otherwise consuming message versions no-one is producing.

Proposed Solution

The proposal is to add an optional version on the message object level to allow for granular versioning.

This in turn will provide more visibility into what has changed, as an application version can change without modifying any of the underlying messages it sends and/or receives.

Example outcome

With the proposed solution, we can fix the message version in the comms-service for messages that haven't changed:

• Comms-service (v1.1.0) receives [payment-success (v1.0.0), payment-failed (v1.0.0), billing-agreement-created (v1.0.0), address-changed (v1.0.0)..] sends [communication-send (v1.1.0)...]

Alternatives

• Using a new message for each version as exemplified in https://eventstack.tech/posts/versioning-is-easy . The downside is that you still need to increase the application version to provide the new version of the application, what in turn means all other messages increases their version.
• Using message traits might be able to provide a version, but feels more of an "weak" link
• Using the specification-extensions, like x-version or x-message-version, can give us also a version to use. While this might work for some extensions, would make it easy for conflicting standarisation when 2/3 ways will compete for a standard version.

NOTE: Not sure if this relates in part to #432 . I made it a different proposal as it seems granular enough.