asyncapi / asyncapi/bindings

[FEATURE] Kafka add `transactional` and `isolationLevel` to operation bindings

Open
#301 3 comments 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?

Kafka's transactional model has two sides that need to be expressed in an
AsyncAPI document:

- A producer that writes transactionally should say so explicitly.
- A consumer reading from a transactional topic should declare the isolation
level it uses, because the default (`read_uncommitted`) exposes it to
messages from aborted transactions.

There is currently no way to express either of these in the binding spec.

### How will this change help?

It will help to properly configure implementing projects with the proper transactionality and isolation level

### Screenshots

_No response_

### How could it be implemented/designed?

## Proposed changes

Both fields are added to the **Operation Binding Object**.

| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
| `transactional` | boolean | Marks this producer as transactional. When `true`, the Kafka client MUST be configured with a `transactional.id` at runtime. | OPTIONAL [`false`] — `send` only | MUST NOT be set on `receive` operations |
| `isolationLevel` | string | The isolation level for this consumer. Controls visibility of messages from transactional producers. | OPTIONAL [`read_uncommitted`] — `receive` only | MUST be one of `read_uncommitted`, `read_committed`. SHOULD be `read_committed` when consuming from a transactional topic |

## Examples

Producer:

```yaml
operations:
publishPaymentEvent:
action: send
bindings:
kafka:
transactional: true
bindingVersion: '0.5.0'
```

Consumer:

```yaml
operations:
consumePaymentEvents:
action: receive
bindings:
kafka:
groupId:
type: string
enum: ['payments-consumer-group']
isolationLevel: read_committed
bindingVersion: '0.5.0'
```

## Notes

The actual `transactional.id` value and its naming strategy are deployment
concerns, not contract concerns. The binding documents intent; the infrastructure
layer owns the runtime value.

End-to-end exactly-once semantics also requires `acks=all` on the producer and
`min.insync.replicas >= 2` on the topic. Those are outside the scope of this
proposal but worth documenting in a follow-up or in a spec note.

## Related

- Kafka docs: [`transactional.id`](https://kafka.apache.org/documentation/#producerconfigs_transactional.id)
- Kafka docs: [`isolation.level`](https://kafka.apache.org/documentation/#consumerconfigs_isolation.level)

### 🚧 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

Start at the Kafka Operation Binding Object definition and review how existing operation fields, send/receive applicability, and binding versions are represented. Implement the proposed transactional and isolationLevel entries with their stated defaults and constraints, then verify the producer and consumer YAML examples reflect the specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
kafka
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.