[spec] AsyncAPI 3.0: Should `OperationObject` be related with a combination of `ChannelObject` & `ServersObject`(s)?

[dishantkamble]

Hi Team,

I have a question on the Spec. I see that the channels have a relation to the server using the servers attribute in the ChannelObject. This is straightforward and makes sense.

I was wondering whether it also makes sense to have an operations related to servers as well (probably something similar to how channels are related in the ChannelObject as mentioned above). Below is the scenario based on which this question comes to my mind.

Scenario

I have a kafka based scenario which i need to represent/design using the asyncAPI spec. The servers are known based on the available environments (e.g. dev, sit, uat, prod). The channels are also identified to be available (lets say) on all servers. All straightforward as per the spec documentation til now.

i.e. if we assume the example to be for a single channel

servers: dev, sit, uat, prod
channels: example.topic

Assume I have a client who is onboarding to the channel, but as the clients need to phase out in an orderly and phased manner, clients are available in the dev -> sit -> uat -> prod, in that order based on controlled release. In such cases, shouldn't the asyncAPI provide mechanism to design operations to also represent on which channel & server combination it is available at any given point in time?

i.e. if we assume the example to be for a single operation

servers: dev, sit, uat, prod
channels: example.topic
operations: readExampleTopic (where operations.<operation-name>.channel: <reference for example.topic>

Effects

The scenario above would in general make the asyncAPI contract, invalid/inconsistent for the developer experience, as the contract would represent that a given operation is available on the channel on ALL servers, whereas it might just be available on (lets say for example) dev & sit at a given moment.

[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.

[Soumya-codr]

Hi @dishantkamble

I understand your scenario - you have the same channel available across all environments, but different operations available on different servers.

The Issue:

AsyncAPI 3.0 doesn't support direct operation-to-server relationships. Operations inherit ALL servers from their referenced channel, so you can't restrict an operation to a subset of the channel's servers.

Your Challenge:

```yaml
# What you want (but AsyncAPI 3.0 doesn't support):
channels:
  example-topic:
    servers: [dev, sit, uat, prod]

operations:
  operation1:
    servers: [dev, sit]  # ❌ Not supported
    channel: 
      $ref: '#/channels/example-topic'

### Solution for your scenario:

Option 1: Environment-specific channels (Recommended)

channels:
  example-topic-lower:
    servers: [dev, sit]
  example-topic-upper:
    servers: [uat, prod]

operations:
  lowerEnvOperation:
    channel:
      $ref: '#/channels/example-topic-lower'
  upperEnvOperation:
    channel:
      $ref: '#/channels/example-topic-upper'

Option 2: Document in descriptions

channels:
  example-topic:
    servers: [dev, sit, uat, prod]

operations:
  operation1:
    description: "⚠️ Available only on dev and sit environments"
    channel:
      $ref: '#/channels/example-topic'
  operation2:
    description: "⚠️ Available only on uat and prod environments"
    channel:
      $ref: '#/channels/example-topic'

Operations cannot be directly related to a subset of servers in AsyncAPI 3.0. Use separate channels per environment group for the most accurate representation.

This limitation suggests a potential enhancement for future AsyncAPI versions.

Hope this clarifies the relationship! Let me know if you need more specific examples for your use case.

[dishantkamble]

Thanks for the response @Soumya-codr , :)

My question was more on to double check regarding is this possible or not, as i saw in the documentation and couldn't find anythings.

I was initially planning to open an RFC for this but thought to double check first with a question, because it is a valid real-world scenario. And with the version 3.0.0, the move of separating out operations from channels, i believe is the perfect state of the spec when this may be considered.

(Or probably not of an alternate interpretation below).

Is it valid (as per the spec) but also from a conceptual stand point to design as,

channels:
  example-topic-lower:
    address: sample.topic.1 # Same topic name
    servers: [dev, sit]
    ...
  example-topic-upper:
    address: sample.topic.1 # Same topic name
    servers: [uat, prod]
    ...

This specific approach, if valid, gives my usecase a workaround (even though a messy one). Meaning even though my topic name is the same, its configuration and properties are same, because i am not able to specifically bind the operations (in this case for receive / send in kafka) with a combination channel and server, I might have to resolve to a workaround of replicating (the exact same details) the channel with different identifier (and also for operations) until any given integrations (operations) using kafka (as well as for other bindings) becomes in-sync across any given channel (topic) on all servers.

Which to me is a significantly long duration and effort for maintaining a state of the spec documentation in sync, not due to valid technical/business changes, but because of the limitation of the spec to represent the current system state at any given point in time, accurately and with ease.

The proposal that I have to include the combination of server + channel, makes it relatively simpler to maintain, as we reuse the spec sections whenever we can. so if the same operation is promoted to higher environments, then we just need to add the server identifier as well in the (new) attribute of the operation and that should be enough. Moreover this new attribute can always be considered optional and in its absence, it will be assumed that the operation is applied to all servers.

What do you think? I believe this is a very valid use-case as all companies have multiple environments, and not all enterprises prefer to differentiate their topic/channel nomenclature. And it will becomes challenging to accommodate such design using the current state of the spec.

Please do let me know if an RFC request is needed to trigger this discussion amongst the maintainers of this repo, so that I can create it soon. :)