Proposal to add a 'version' value into the message object to support a more granular versioning
- Dominant language
- JavaScript
- Stars
- 5.3k
- Forks
- 382
- Avg merge
- 7m
- Merged PRs (30d)
- 4
Description
# Introduction
This proposal is to add a `version` field into the [message object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#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](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-object) 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](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageTraitObject) might be able to provide a version, but feels more of an "weak" link
* Using the [specification-extensions](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#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.
Contributor guide
Research direction
Start with the linked Message Object section in the AsyncAPI specification and review issue #432 for related versioning context. Compare the proposed optional message-level version with message traits and specification extensions; done means the project reaches a decision and the specification reflects the accepted versioning approach.
Written by the indexing model from the issue text.
Assessment
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100