asyncapi / asyncapi/bindings

[FEATURE] Kafka: add schema `compatibility` field to message binding

Open
#304 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
No language data
Stars
79
Forks
81
PR merge metrics
No merged PRs in 30d

Description

### Why do we need this improvement?

When using a schema registry, the compatibility mode is part of the contract
between producers and consumers. There is currently no way to document it in
an AsyncAPI message binding.

### How will this change help?

Teams reading the AsyncAPI document know immediately what compatibility
guarantee the schema is registered under. Tooling that registers schemas
from AsyncAPI documents can apply the correct compatibility setting without
external configuration.

### Screenshots

_No response_

### How could it be implemented/designed?

Add a `compatibility` field to the Message Binding Object.

| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
| `compatibility` | string | The schema compatibility mode used when registering this schema. | OPTIONAL | MUST be one of `BACKWARD`, `BACKWARD_TRANSITIVE`, `FORWARD`, `FORWARD_TRANSITIVE`, `FULL`, `FULL_TRANSITIVE`, `NONE` |

```yaml
messages:
PaymentEvent:
bindings:
kafka:
schemaIdLocation: 'payload'
schemaLookupStrategy: 'TopicNameStrategy'
compatibility: 'BACKWARD'
bindingVersion: '0.6.0'
```

The enum values follow the compatibility types defined by Confluent Schema
Registry and supported by Apicurio Registry and Karapace.

### 🚧 Breaking changes

No

### 👀 Have you checked for similar open issues?

- [x] I checked and didn't find a similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Research direction

Begin at the Kafka Message Binding Object and compare the proposed YAML example with its existing fields. Done means the optional compatibility field is documented and accepts exactly the seven listed Confluent compatibility values without introducing a breaking change.

Written by the indexing model from the issue text.

Assessment

Tech stack
kafka
Domain
backend-api-design
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.