[FEATURE] Kafka Channel Binding Property for Environment-Specific Overrides

[ivangsa]

Why do we need this improvement?

Motivation

Kafka topics frequently require different settings per environment:

• Lower partitions / replicas in dev environments
• Shorter retention policies in non-production
• Reduced storage limits for cost control
• Different cleanup strategies

Without native support, teams can not use AsyncAPI as the single source of truth for both API contract and infrastructure deployment. They typically rely on:

• External deployment logic
• Custom templating systems

This increases complexity and reduces portability. Embedding overrides improves clarity, reduces duplication, and aligns infrastructure intent with the API contract.

How will this change help?

Summary

This proposal introduces a Kafka channel binding property that enables environment-specific overrides of topic configuration within an AsyncAPI document. This property provides a standardized, explicit mechanism to declare such differences directly within channel bindings so AsyncAPI can be the single source of truth for both API contract and infrastructure deployment.

Screenshots

No response

How could it be implemented/designed?

Proposed Property

Introduce a new property at the Kafka channel binding level:

channelBindings:
  someKafkaChannelBinding:
    kafka:
      partitions: 20
      replicas: 3
      topicConfiguration:
        cleanup.policy: ["delete", "compact"]
        retention.ms: 604800000
        retention.bytes: 1000000000
        delete.retention.ms: 86400000
        max.message.bytes: 1048588
      envServerOverrides:
        dev:
          partitions: 1
          replicas: 1
          topicConfiguration:
            cleanup.policy: ["delete"]
            retention.ms: 604800
        staging:
          partitions: 3
          replicas: 2

Semantics

• The base kafka binding defines the default topic configuration.
• env-server-overrides defines partial overrides applied conditionally.
• Keys under env-server-overrides correspond to server names defined in the AsyncAPI document.
• Each override object follows the same schema as the Kafka channel binding but allows partial definitions.
• Overrides are applied as a merge on top of the base binding.

Resolution Rules

When using AsyncAPI channel bindings to provision Kafka topics, the following rules apply:

1. Identify the active server (tooling / runtime decision).
2. Match the server name against env-server-overrides.
3. Merge override fields onto the base Kafka binding.
4. Unspecified properties inherit base values.

Validation Considerations

• Override keys are expected to correspond to existing servers entries.
• Override objects should follow the Kafka channel binding structure.

Naming Discussion

The proposed name is env-server-overrides.

Rationale:

• env communicates intent (environment-dependent behavior)
• server aligns with AsyncAPI's existing server model
• overrides clearly expresses merge semantics

env-server-overrides explicitly ties overrides to AsyncAPI server definitions rather than arbitrary environment labels.

Future Considerations

• Would this property be useful for other protocols?

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

Yes I am willing to submit a PR!

[github-actions]

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.