docs: clarify bundling behavior on Schema Object #653
Conversation
smoya
added
the
✏️ Editorial
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide 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.
spec/asyncapi.md
Outdated
| @@ -1670,6 +1669,7 @@ The following properties are taken from the JSON Schema definition but their def | |||
| - default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. | |||
|
|
|||
| Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. | |||
| It is appropriate to clarify that the `$ref` keyword will follow the behavior described by [Reference Object](#referenceObject) **and not** the one in JSON Schema definition. Therefore, `$id` keyword won't modify the behavior of `$ref`. | |||
There was a problem hiding this comment.
To further clarify this problem people will need to wrap their head around what $id is and do (we don't describe any of this in the schema object), what JSON Schema is, how it relates to the default super-set of JSON Schema, and this is not relevant to users if they aren't using JSON Schema at all (hope that made sense 😅)
Not sure if we can really clarify this, on the other hand, it is kinda needed... Idk how we can solve this 🙃 😆
There was a problem hiding this comment.
I think I see your point. However, I would like to clarify some things first:
we don't describe any of this in the schema object
In the "Schema Object" section, we mention it is a superset of JSON Schema Draft-07, including a link to the core and validation documents. Also, we have this statement As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to
So IMHO it is clear there is a relation and the fact we directly depend on JSON Schema Draft-07 spec.
Is it enough with just having those lines? Do you suggest we expand the information further?
There was a problem hiding this comment.
But it also states further down:
Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions in place of defining them inline.
Which is even more confusing, when they have nothing to do with each other 😆
There was a problem hiding this comment.
I removed the reference to $id plus removed the linebreak so it stick all together. Also added a link to the JSON Schema reference docs. Hope that makes more sense now @jonaslagoni !
Co-authored-by: Fran Méndez <[email protected]>
|
/rtm |
|
Kudos, SonarCloud Quality Gate passed!
|
|
/rtm |
|
🎉 This PR is included in version 2.3.0-2022-01-release.1 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version 2.3.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This PR clarifies the behavior of bundling and (de)referencing of Schema Object, introducing a clear statement and reminder that the
$refbehavior does not follow JSON Schema one, therefore things like$idwon't have any effect on it.Related issue(s):
#649