Is there a way to document the guaranteed compatibility mode for produced messages?

[thake]

We plan to use AsyncAPI as our way to document asynchronous APIs. I was wondering if there is a standardized way of communicating the guaranteed compatibility mode of produced messages. For example, confluent schema registry knows the following compatibility modes:

• BACKWARD
• BACKWARD_TRANSITIVE
• FORWARD
• FORWARD_TRANSITIVE
• FULL
• FULL_TRANSITIVE
• NONE

I would like to make the compatibility mode part of the contract specified by the AsyncAPI spec, but couldn't find any standardized way. Clients which are programmed against the AsyncAPI spec can rely on the compatibility mode. A new version will only be introduced if the compatibility according to the compatibility mode is no longer given.

Is there support for this without specification extensions? If not, do you think this would be a good addition to the spec?

[dalelane]

That's an interesting idea. For a historical description of changes-until-now, you could just put them all in the AsyncAPI doc wrapped in a one-of so I suspect there wouldn't be any need to additionally describe the compatibility.

But I can see this being super useful for a more forward-looking "contractual" commitments (e.g. by specifying the compatibility mode in the AsyncAPI doc, an author can make an ongoing commitment that future versions of the doc/schema will have a certain level of compatibility)

I haven't seen this done in AsyncAPI docs before, but I think it's worth exploring.

I suspect this will be more useful for Kafka than some other protocols - or at least protocols that support retaining old/previous events. And certainly that would make it easier to adopt the Apache Avro approach to describing compatibility more or less as-is. But I don't think it'd hurt to try doing it in a protocol-agnostic way, as there's nothing stopping other protocols using Avro or making commitments about future changes, even if it's more common in Kafka.

[thake]

Thanks for the feedback, @dalelane!

That's an interesting idea. For a historical description of changes-until-now, you could just put them all in the AsyncAPI doc wrapped in a one-of so I suspect there wouldn't be any need to additionally describe the compatibility.

I'm not so sure if one-of can be used to describe backward compatible historical changes. As the changes are backward compatible, meaning a newer schema can be used to read messages written with an older schema, one central requirement of one-of is not met: "a message MUST be valid only against one of the message objects". Thus, even documenting that a produced event message is backward compatible might be useful.

I agree with you regarding documenting incompatible changes: One-of is the way to go for documenting historic versions.

I haven't seen this done in AsyncAPI docs before, but I think it's worth exploring.

I haven't seen it in AsyncAPI docs either. But I've seen the usage of "compatibility mode" in other event specifications. Zalando makes specifying the compatibility mode mandatory: https://opensource.zalando.com/restful-api-guidelines/#245.

I suspect this will be more useful for Kafka than some other protocols - or at least protocols that support retaining old/previous events. And certainly that would make it easier to adopt the Apache Avro approach to describing compatibility more or less as-is. But I don't think it'd hurt to try doing it in a protocol-agnostic way, as there's nothing stopping other protocols using Avro or making commitments about future changes, even if it's more common in Kafka.

I totally agree that the compatibility mode should be made protocol-agnostic.

Besides clearly communicating expectations to consumers, I can think of the following usages of a compatibility mode in the AsyncAPI spec:

• tooling can be provided to check if changes to the message respect the compatibility mode by comparing it to previous message schemas.
• schema registries having the concept of compatibility can be configured with one single source of truth: AsyncAPI specs.

[github-actions]

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

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 ❤️

[jonaslagoni]

Somewhat related to #697

[github-actions]

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

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 ❤️