[3.0.0] Clarify operation object channel reference

[jonaslagoni]

Given the following AsyncAPI document:

asyncapi: '3.0.0'
info:
  title: 'Account Service'
  description: 'This service is in charge of processing user signups'
channels:
  UserSignedUp:
    $ref: './channels/UserSignedUp.yaml'
operations:
  ConsumeUserSignedUp:
    action: receive
    channel: 
      $ref: '#/channels/UserSignedUp'

Should the #/operations/ConsumeUserSignedUp/channel be a reference to the local channels defined with the root #/channels/UserSignedUp or can it be a reference to the external common definition ./channels/UserSignedUp.yaml?

The current definition for channel says:

Required. A $ref pointer to the definition of the channel in which this operation is performed. Please note the channel property value MUST be a Reference Object and, therefore, MUST NOT contain a Channel Object. However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.

Which I would argue does not clarify this... So what is the intended behavior? I assume it's a reference to the root channel #/channels/UserSignedUp, right?

[magicmatatjahu]

@jonaslagoni I also have a problem with current channels - my comment about it asyncapi/parser-js#654 (comment)

I think that you can make reference to channel in operations[x].channel from external document, but that channel should be also referenced inside channels section, like:

asyncapi: '3.0.0'
info:
  title: 'Account Service'
  description: 'This service is in charge of processing user signups'
channels:
  UserSignedUp:
    $ref: './channels/UserSignedUp.yaml'
operations:
  ConsumeUserSignedUp:
    action: receive
    channel: 
      $ref: './channels/UserSignedUp.yaml'

Important thing is that './channels/UserSignedUp.yaml' should be referenced in channels section, in other places you can use './channels/UserSignedUp.yaml' or $ref: '#/channels/UserSignedUp' whatever you want - in other words it have to be this same object. But... I think that it would be good if you can make only this:

asyncapi: '3.0.0'
info:
  title: 'Account Service'
  description: 'This service is in charge of processing user signups'
operations:
  ConsumeUserSignedUp:
    action: receive
    channel: 
      $ref: './channels/UserSignedUp.yaml'

and spec should be valid, because operations.ConsumeUserSignedUp.channel points to some valid channel. The problem is if we should treat then operations.ConsumeUserSignedUp.channel as part of channels section? 🤔

[jonaslagoni]

That just goes against the definition of what channels are for the root object which is defined as:

An object containing all the Channel Object definitions the Application MUST use during runtime.

I kinda read it as you must specify all the channels your application uses here, which technically is not the case as it's more Any channels defined under this section MUST be used by the application at runtime.

The problem is if we should treat then operations.ConsumeUserSignedUp.channel as part of channels section

I think that would create more confusion tbh, but feel free to suggest it 😄

Here are the questions that I suggest the spec should clarify:

1. Should the #/operations/ConsumeUserSignedUp/channel be a reference to the local channels defined with the root #/channels/UserSignedUp or can it be a reference to the external common definition ./channels/UserSignedUp.yaml
2. Is the root channels property to be interpreted as you must specify all the channels your application uses here or Any channels defined under this section MUST be used by the application at runtime?

Answering the above questions should IMO clarify how it is to be used. Can you think of other specific questions you can ask that would clarify the current setup?

After these questions are answered we can always add new issues suggesting other approaches :D

[magicmatatjahu]

Should the #/operations/ConsumeUserSignedUp/channel be a reference to the local channels defined with the root #/channels/UserSignedUp or can it be a reference to the external common definition ./channels/UserSignedUp.yaml

Both references are good for me, but as I wrote, operations.ConsumeUserSignedUp.channel should be one of object defined in `channels, it's not important reference path, but it's important if it points to this same object. Let's not make such a restrained specification here 😄

Is the root channels property to be interpreted as you must specify all the channels your application uses here or Any channels defined under this section MUST be used by the application at runtime?

I think you must specify all the channels your application uses here should be better description for it.

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