fix: deprecate $ref property in Channel Item Object
#696
Conversation
| @@ -565,7 +565,7 @@ Describes the operations available on a single channel. | |||
|
|
|||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="channelItemObjectRef"></a>$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. | |||
| <a name="channelItemObjectRef"></a>$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. <br><br>**Deprecated:** Usage of the `$ref` property has been deprecated. | |||
There was a problem hiding this comment.
I think we should give a better explanation on the reason for deprecating. Like mentioning we deprecate it in favor of using Reference Object from the Channels Object instead of Channel Item Object. WDYT? cc @fmvilas @jonaslagoni
There was a problem hiding this comment.
If we say we deprecate in favor of Reference Object it may indicate that future versions will use Reference Object, but later versions of the spec might handle this quite differently. Best way to probably handle this is to have wording self-contained withing the version of the spec this RFC targets - and the sentence I put there was the only one I could come up with. I'm really open to suggestions here ;]
There was a problem hiding this comment.
I'm fine if others see it make sense 👍
|
@char0n I think this should be a |
char0n
force-pushed
the
char0n/rfc-channel-item-refs
branch
from
a88f5e2 to
5c06b72
Compare
|
Kudos, SonarCloud Quality Gate passed!
|
char0n
changed the title
|
@smoya I've force-pushed to change the commit msg type |
FYI, for next time you just only need to change the PR title instead of the commit, because the squashed merged commit uses the PR title as commit message. |
|
@char0n Additionally, would you like to provide some words regarding this change for the |
|
@smoya yes that would be a great medium where to describe the deprecation plan of the |
|
e.g. "channelItem": {
...
"properties": {
"$ref": {
"$ref": "#/definitions/ReferenceObject",
"deprecated": true
},Update: Never mind - ignore me. "deprecated" was added in JSON schema draft-08 and we're using draft-07 - so we can't add that. |
|
@smoya Do you think anything else is needed to be able to approve and merge this? |
OK on my side! Also a +1 from an Owner is already provided 👍 |
derberg
changed the title
$ref property in Channel Item Object
|
this one was pretty interesting and education read 😄 @char0n please have a look at the change I did in PR title, I think most important is to highlight deprecation in the release notes also can you please extend description of this issue so reader of release notes, that will end up in this PR doesn't have to go through a long discussion from the issue but have a summary here in PR description? |
Yeah, change in PR title looks good. @dalelane did a great job in verbalizing the proper deprecation message in https://github.com/asyncapi/website/pull/512/files#diff-a43f6e629535a43413950aefe222b7d7e591e50515314573ff440e91b8aaed8aR66
I'll do my best ;] |
|
/rtm |
|
🎉 This PR is included in version 2.3.0-2022-01-release.3 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Fixes #607
Summary:
This PR builds on top #665 which introduced
Components.channelsfield without need to revert it, is aligned with release strategy described below (ref: #607 (comment)) and eliminates the ambiguity betweenChanne Item ObjectandReference Object$reffield.Release strategy
AsyncAPI 2.x
The aim here is to limit complexity and bring more flexibility. Resolution rules around
Channel Item Object.$reffield are not so clear: #612$reffixed field inChannel Item ObjectchannelsinComponents Objectwith type of Map[string,Channel Item Object]AsyncAPI 3.x.
The aim here is to have single referencing mechanism within AsyncAPI 3.x spec (reducing complexity) -
Reference Object$reffromChannel Item Objectfixed fieldsChannel Objectpatterned field type toReference Object | Channel Item ObjectComponents Object.channelsfield type will change to Map[string,Channel Item Object|Reference Object]