-
-
Notifications
You must be signed in to change notification settings - Fork 273
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
Unify reference and bundling behavior with JSON Schema #649
Comments
Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request. |
A PR with a clarification of the bundling and (de)reference behavior of Schema Object has been opened: #653 |
For the record, there is a recent effort on building JSON Schema foundational tooling with kind of (TBD) official support, lead by @jviotti and @Relequestual here json-schema-org/community#113. |
@smoya You have to remember that referencing in a JSON Schema (compared to a regular JSON Pointer) differs not only because of additional keywords like It seems to me that the most sensible solution would be to support referencing in the AsyncAPI document according to the JSON Pointer guidelines, and in the case of schemas that have been defined as JSON Schema referencing according to the JSON Schema Pointer - similarly to OpenAPI, you can use |
Ok, this is quite embarrassing. I wrote a comment in this issue a few days ago but didn't end being posted. I guess due to a failure in the request to Github and me closing the tab without noticing. Life is wonderful ✨ Let's try again! Both @jonaslagoni and I have been investigating a bit about Just to summarize, the important part is giving an answer to "What features of JSON Schema reference and bundling system we consider suitable for AsyncAPI?"
asyncapi: '2.2.0'
info:
title: Test $ref
version: '1.0.0'
channels:
test:
publish:
message:
$ref: '#/components/messages/myMessage'
name: "Awesome Message" # this value should take precedence and override the original `name` field.
components:
messages:
myMessage:
name: original name
As per my comment in #596 (comment), overriding properties is not a thing in JSON Schema
We (@jonaslagoni and I) couldn't find an official doc place where they mention this, however you can find some mentions on this library issue APIDevTools/json-schema-ref-parser#145 (comment) (from where I got the example above) and also this Slack thread where @jonaslagoni is involved https://json-schema.slack.com/archives/CT8QRGTK5/p1637146426080000?thread_ts=1636976501.051400&cid=CT8QRGTK5 Having said that, I'm suggesting we close this issue as a won't do. Instead, to work on:
I hope this also answers @magicmatatjahu comment. WDYT? |
@smoya Thanks! I know about problems (I read all issues that you and Jonas created related to pointers), but maybe for other this comment will be very helpfull.
It is a way out, but we should reuse existing tools as much as possible.
I can't find information if
As far as
I agree with you that we should support overrides, but as normal overrides and not with logic from JSON Schema with And I'll say it again. Pointers in JSON Schema should only point to JSON Schema instances, i.e. JSON object that is a valid JSON Schema or boolean value, everything else is forbidden. This is a serious problem because we have planned to support also other schema formats like XSD, Protobuf, GraphQL and without string referencing we will not be able to achieve this, so my suggestion:
There is also an option to make a deal with JSON Schema team to have their specification for JSON Pointers extracted from spec, but with the ability to reference primitives like string, number etc :) |
@magicmatatjahu we are talking about the same. Maybe I didn't clarify it properly in my previous comment but my suggestion is exactly that, to have two reference/bundling systems:
Considered as stated in the second bullet in "Possible next steps" in the body of this issue (except for suggesting support for referencing primitives). |
Agreed, however as I see it the fact is there are no tools that actually fully support either, so building the tools becomes inevitable, especially if we want to support other languages than JS. So we might as well find an optimal solution. I don't see any reason to "merge" reference behavior with JSON Schema, because of this:
That leaves the question, would it be confusing for people if asyncapi: '2.2.0'
...
channels:
test/channel/1:
publish:
message:
$ref: '#/components/messages/test1'
test/channel/2:
publish:
message:
schemaFormat: application/schema+json;version=draft-07
payload:
$id: 'http://asyncapi.com/schemas/test2'
type: object
properties:
test:
$ref: 'test3' And with 2019-09 and beyond: schemaFormat: application/schema+json;version=draft-2019-09
payload:
$id: 'http://asyncapi.com/schemas/test2'
type: string
$ref: 'test3' If yes, then I think we should introduce a different keyword. |
That was totally my point. If I think of myself a few weeks ago, I would say it is confusing (a lot). However today, I'm totally biased because I went down the rabbit hole 😅 . We might need more input from other users. |
While writing my comment I knew that it might be confusing for users that there are different referencing logics in different places, but I stayed with Looking at the referencing problem in general and how it has impact on spec, I wonder if we will be able to solve these problems in 3.0.0 or rather in 4.0.0 spec? |
Will it be worth it is of course the question 😄 But with the current state of tooling, it might not be that much different.
Don't think we should target one or the other, lets see if we can figure out what to do about it first 😄 Cause if we do decide on switching, we need to create a new tool before we can merge in the spec 🙂 |
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
This issue has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation. There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
This would make the most sense to me. I see some confusion/concern here over the use case for
This is an important consequence of JSON Schema's architecture that is worth understanding: It is a constraint system, not a data definition system. In a constraint system This means that a "base" schema cannot provide default constraints, unless those constraints are minimal (all "child" schemas will be more constrained, not less or differently constrained). So you end up with a different pattern of where and how you mix in default behavior in JSON Schema than you would in an OO programming langauge. Also, (although this is a personal opinion that is being debated but not yet adopted by the JSON Schema org), I would strongly recommend not bothering with 2019-09. It was not out long enough to get broadly adopted before 2020-12 came out, and 2020-12 being adopted by OAS 3.1 means that there will be a much greater demand for 2020-12 tooling. |
It might be helpful to consider how we use There was a question about how we refer to schemas within an Avro avsc file (where the avsc file contains multiple record definitions) in #414. I think we are perhaps a little ambiguous about how that should be done, as the raiser of that issue had a different interpretation to me. |
I think this issue can be closed in favor of #825, where all those requirements are put in common. WDYT @dalelane @handrews @jonaslagoni ? |
Closing in favor of #825. |
Context
Current AsyncAPI Reference Object documentation mentions:
On the other hand, JSON Schema Draft-07, the version current AsyncAPI spec relies on, does not follow JSON Reference but rather its own implementation.
JSON Schema Draft-07 includes the
$id
keyword which modifies the behavior of$ref
. It allows defining a base URI for the$ref
keyword, where referenced URIs will be taken as relative to the one in$id
.On the contrary,
$id
property is not allowed on any AsyncAPI object.Why is this a problem?
We do not have a unified reference object behaviour between AsyncAPI Reference Object and JSON Schema Draft-07. That impacts directly the user experience.
Tooling must support two different dereferencing and bundling behaviors:
The following issues have been created:
Tooling availability is a problem as well. As there is no standard spec we all (AsyncAPI, OpenAPI, etc) can follow, tooling will need to be customized.
Possible next steps
1. Porting the same dereference + bundling resolution behavior as JSON Schema does
For the case of JSON Schema Draft-07, will be adding support for
$id
keyword.In the case we decide to eventally update to JSON Schema Draft 2020-12, some other keywords and behaviors will be supported, such as allowing extra properties when using
$ref
.2. Work with JSON Schema community to unify efforts by moving reference behavior to its own document
Meaning anyone would be able to reference that document from their own spec schemas.
Some questions to be answered:
3. Only porting bundling behavior but not referencing one.
An alternative to the first point could be to only port the bundling behavior from JSON Schema and skip referencing one.
Meaning, things like allowing extra properties when using
$ref
which got introduced in JSON Schema Draft 2019-09 could be adopted, however support for$id
keyword will be discarded.4. Accepting that there is a difference
We might want to clarify it even more in our docs.
Suggestion
I would suggest we follow this combo:
What do you all think? Looking for comments!
cc @Relequestual
The text was updated successfully, but these errors were encountered: