fix: clarify pointers for channel.servers and operation.channel fields

[smoya]

Fixes #991

Please help me writing proper sentences. Feel free to suggest changes.

[fmvilas]

Why not making it more explicit?

Suggested change

<a name="channelObjectServers"></a>servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. It MUST point to a subset of server definitions located in the [Servers Object](#serversObject) and MUST NOT point to a subset of server definitions located in the [Components Object](#componentsObject). If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.

<a name="channelObjectServers"></a>servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. This value MUST start with `#/servers/`, meaning only pointing to the [root servers object](#serversObject) is allowed. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience.

[derberg]

you cannot be explicit, you can have channel defined in a separate file and then the $ref to server would not start with #/servers

[smoya]

Exactly. Technically it should contain the string #/servers but not necessary in the beginning of the pointer. In fact that's what the Spectral rule checks https://github.com/asyncapi/parser-js/blob/next-major-spec/src/ruleset/v3/ruleset.ts#L56 but you @fmvilas already know because you reviewed my PR and, in fact, you suggested it iirc.

[fmvilas]

You're right. So then the parser can't implement it this way either, right? @smoya

[smoya]

You're right. So then the parser can't implement it this way either, right? @smoya

But the rule only applies to objects (Channels, Operations...) defined in the root. See https://github.com/asyncapi/parser-js/blob/next-major-spec/src/ruleset/v3/ruleset.ts#L51

If in components, "all" is allowed.

[fmvilas]

Hmmm 🤔 I still don't think it's correct. Unless we avoid the parser to resolve these references.

[smoya]

The Spectral rule applies before resolving the references. Not sure if this "answers" your question.

[fmvilas]

Same as with servers.

[derberg]

you also need to update definition of channel reference in Operation Reply Object

and yeah, same with message -> #991 (comment)

[derberg]

you cannot be explicit, you can have channel defined in a separate file and then the $ref to server would not start with #/servers

[derberg]

examples fix #997

[jonaslagoni]

I have some use cases I want to run by you and you let me know which rules are applied.

• Use case 1: A root channel is defined as a reference, and the operation references that root channel. How do you define the message reference? To the root channel or the channel in the components section?

{
    asyncapi: 3.0.0,
    channels: {
        test: {
            $ref: '#/components/channels/test'
        }
    },
    operations: {
        operationTest: {
            channel: {
                $ref: '#/channels/test'
            },
            messages: [
                {
                    $ref: '#/channels/test/messages/test'
                }
            ]
        }
    },
    components: {
        channels: {
            test: {
                messages: {
                    test: {},
                    test2: {}
                }
            }
        }
    }
}

• Use case 2: You use AsyncAPI to define a menu of channels and operations. Are operations allowed to reference channels in components?

{
    asyncapi: 3.0.0,
    components: {
        channels: {
            test: { ... }
        },
        operations: {
            operationTest: {
                channel: {
                    $ref: '#/components/channels/test'
                }
            }
        }
    }
}

[smoya]

I have some use cases I want to run by you and you let me know which rules are applied.

• Use case 1: A root channel is defined as a reference, and the operation references that root channel. How do you define the message reference? To the root channel or the channel in the components section?

Technically, your example is compliant.
User friendly? Might sound a bit confusing indeed. In addition, I believe confusion increases due to the usage we are giving to JSON Reference in these cases (channels.servers, operations.channel, operations.messages, operationReply.channel, operationReply.messages), where they represent just "an ID" of the referenced object VS the rest of the document which are indeed JSON References that are expected to be dereferenced. In fact, and for example, the current description in v3 for operation.channel field says:

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.

I would not allow, in this case, a ref to the message in components even though it is the same referenced in the linked channel because once everything gets dereferenced, those channels.servers, operations.channel, operations.messages, operationReply.channel, operationReply.messages will still be presented as references.
We could, however, improve our Spectral rule to detect these cases and, instead of just throwing the current error, be more user friendly specifying that even though they both point to the same message, they need to point to the root object. Not strong opinion and not very willing to do that but 🤷 .

• Use case 2: You use AsyncAPI to define a menu of channels and operations. Are operations allowed to reference channels in components?

Operations inside components can reference to either channel or messages from components or from root.

[smoya]

@jonaslagoni I think I managed to clarify a bit the use cases you showed in your comment.

Also I improved the wording and added clarifications in operation reply object as well. Please all of you take a look 🙏 @fmvilas @derberg

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[derberg]

I don't think it can be done clearer 👏🏼

[fmvilas]

I don't think it can be done clearer 👏🏼

Indeed!

[fmvilas]

/rtm

[asyncapi-bot]

🎉 This PR is included in version 3.0.0-next-major-spec.17 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[smoya]

Even though this has been merged now, can you @jonaslagoni confirm your concerns about thos edge cases are now clarified with my changes added in the spec? thank you! 🙏

[jonaslagoni]

Gonna give it another read when I am doing the converter update