-
-
Notifications
You must be signed in to change notification settings - Fork 280
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix: clarify pointers for channel.servers and operation.channel fields #996
fix: clarify pointers for channel.servers and operation.channel fields #996
Conversation
8ca5060
to
042921a
Compare
spec/asyncapi.md
Outdated
@@ -634,7 +634,7 @@ Field Name | Type | Description | |||
<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the channel. | |||
<a name="channelObjectSummary"></a>summary | `string` | A short summary of the channel. | |||
<a name="channelObjectDescription"></a>description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. | |||
<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. 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. 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not making it more explicit?
<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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
you cannot be explicit, you can have channel defined in a separate file and then the $ref to server would not start with #/servers
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You're right. So then the parser can't implement it this way either, right? @smoya
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmmm 🤔 I still don't think it's correct. Unless we avoid the parser to resolve these references.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Spectral rule applies before resolving the references. Not sure if this "answers" your question.
spec/asyncapi.md
Outdated
@@ -830,7 +830,7 @@ Describes a specific operation. | |||
Field Name | Type | Description | |||
---|:---:|--- | |||
<a name="operationObjectAction"></a>action | `"send"` | `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). | |||
<a name="operationObjectChannel"></a>channel | [Reference Object](#referenceObject) | **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](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. | |||
<a name="operationObjectChannel"></a>channel | [Reference Object](#referenceObject) | **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](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. It MUST point to a channel definition located in the [Channels Object](#channelsObject) and MUST NOT point to a channel definition located in the [Components Object](#componentsObject). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as with servers.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
you also need to update definition of channel reference in Operation Reply Object
and yeah, same with message -> #991 (comment)
spec/asyncapi.md
Outdated
@@ -634,7 +634,7 @@ Field Name | Type | Description | |||
<a name="channelObjectTitle"></a>title | `string` | A human-friendly title for the channel. | |||
<a name="channelObjectSummary"></a>summary | `string` | A short summary of the channel. | |||
<a name="channelObjectDescription"></a>description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. | |||
<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. 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. 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
you cannot be explicit, you can have channel defined in a separate file and then the $ref to server would not start with #/servers
examples fix #997 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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'
}
}
}
}
}
Technically, your example is compliant.
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.
Operations inside components can reference to either channel or messages from components or from root. |
@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 |
Co-authored-by: Fran Méndez <fmvilas@gmail.com>
Co-authored-by: Fran Méndez <fmvilas@gmail.com>
Co-authored-by: Fran Méndez <fmvilas@gmail.com>
Co-authored-by: Fran Méndez <fmvilas@gmail.com>
Co-authored-by: Fran Méndez <fmvilas@gmail.com>
Kudos, SonarCloud Quality Gate passed! 0 Bugs No Coverage information |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think it can be done clearer 👏🏼
Indeed! |
/rtm |
5fb88a0
into
asyncapi:next-major-spec
🎉 This PR is included in version 3.0.0-next-major-spec.17 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
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! 🙏 |
Gonna give it another read when I am doing the converter update |
Fixes #991
Please help me writing proper sentences. Feel free to suggest changes.