Proposal to add a 'version' value into the message object to support a more granular versioning

[IsmaelMartinez]

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 https://github.com/asyncapi/spec/issues/432 . I made it a different proposal as it seems granular enough.

[github-actions[bot]]

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]

I'm all in with this proposal. Just want to leave a note on the following:

This inherently implies that all messages are of the same version, or that events do not hold a version at all.

I think it's more like the latter. The version of the application has nothing to do with the version of the messages. This surely can be clarified.

[IsmaelMartinez]

Sure, in my case the implementation of this in EventCatalog has assumed the events has a version, what has created the problem for me.

I agree the spec don't imply events have a version. Do you want to edit my message/proposal ? Not sure how this contributions work on that aspect, and if the proposal gets edited or not. Thanks a lot!

Also, if this gets approved, I am happy to make the changes in the parser, spec files, etc. It shouldn't be a big job (famous last words)...

[smoya]

I +1 this. I believe it is a good addition @IsmaelMartinez 💯

[fmvilas]

Do you want to edit my message/proposal ?

No, I think that's fine. Just wanted to clarify it 👍

[jonaslagoni]

Sounds like a good proposal yea 👍 Maybe make global version optional 🤔

[IsmaelMartinez]

Sounds like a good proposal yea 👍 Maybe make global version optional 🤔

Can that be for another RFC ? Otherwise changes can grow arms, legs and tentacles ;)

There doesn't seem to be any opposition to the matter. Reading the CONTRIBUTING.md I understand there are a few promotion steps that needs to happen and then a few changes to the parser and other projects.

I would be happy to start making those PRs just to have them ready for when that promotion happens. Just let me know if I am jumping the gun. Ta