feat: rename $ref to ref #912
Conversation
|
|
|
Kudos, SonarCloud Quality Gate passed!
|
| @@ -1934,7 +1934,7 @@ The following properties are taken from the JSON Schema definition but their def | |||
| - format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. | |||
| - 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 MUST follow the behavior described by [Reference Object](#referenceObject) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#ref). | |||
| 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 MUST follow the behavior described by [Reference Object](#referenceObject) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#ref). | |||
There was a problem hiding this comment.
Need to clarify this. It should be a JSON Schema Reference Object, not our Reference Object.
| @@ -1607,20 +1607,20 @@ For this specification, reference resolution is done as defined by the JSON Refe | |||
| ##### Fixed Fields | |||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="referenceRef"></a>$ref | `string` | **REQUIRED.** The reference string. | |||
There was a problem hiding this comment.
The description of the Reference Object above should be updated too, to reflect that it's not strictly oriented to JSON format only and it may change in the future. Otherwise, it would be a breaking change.
fmvilas
requested review from
derberg,
dalelane,
smoya,
char0n and
asyncapi-bot-eve
as code owners
There was a problem hiding this comment.
It's not that easy
Waving your hand and changing the spec, is the easiest decision you can do.
The problem is that we have NO tooling that supports this renaming or can be easily adapted to do so.
The reason everything seems to work at the moment is that there is almost no difference between resolving a reference in AsyncAPI, OpenAPI, or JSON Schema. It's only when you start using JSON Schema-specific referencing logic it falls apart.
What I am trying to say is that there we have not found a library that can dynamically change it's behavior based on the underlying specification and where the reference is located within the document. Cause even with this change you will still need to have a referencing library that can dereference $ref from the other standards.
This means this change will further break this illusion of references working.
Unless you have a plan in place to create the right referencing tooling for version 3? I mean we need it at some point anyway, and I personally know I will start looking into it after v3, but I don't see this happening right now. Happy to be wrong though 😄
|
tbh I do not get how this change is helping and prevents any future breaking changes. I think it is just a matter of making sure In OpenAPI 3.1 you can see https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.1.0.md#reference-object We could have the same (not summary and description), and in future have another field where one can specify that reference is to proto or xsd, or in general non-json |
|
You're both right. Closing it! |
@fmvilas and what do you think about 👆 |
|
Yeah, I like that solution. We just use a different JSON Reference object. That should be fine 👍 |
So as promised in the Spec 3.0 call today, here's my PR 😂
With this change, I'm trying to prevent a future breaking change if we start accepting references to Protobuf or XSD, or any other non-JSON formats. We will define the behavior of the JSON Reference object. As of today, we keep the same behavior so nothing else changes but the name (
$ref->ref). Whenever we think we're ready to ship non-JSON referencing support, it would be just a matter of augmenting the behavior of the JSON Reference object, making it a non-breaking change.What do you think?