-
-
Notifications
You must be signed in to change notification settings - Fork 262
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
Unifying when reference can be used #650
Comments
Please have in mind (or you had it writing this issue) that string, number, boolean, object and array (and null) are JSON instances (RFC 8259), so if you write about However, I prefer the first proposal in order to simplify the use of references in general, as well as to allow referencing of primitives - the description of the AsyncAPI document in the |
I found an article https://www.asyncapi.com/blog/the-reference-rabbit-hole and it was linking to this issue. Id' like to join the discussions with my observations. @jonaslagoni we had similar discussion with you and other maintainers in: #552 and #579. I'll be quoting sections from the article and expressing my thoughts about quotes.
This is what the specification tell us about it: This clearly defines what
Specification clearly states here, that Servers Object only allows
IMHO this whole section is not what specification tells us. As mentioned above every
I mostly agree with observation of this section. But it should be pointed out, that there is only one referencing mechanism allowed in the AsyncAPI spec and that is
As mentioned above, it shouldn't really matter as the specification clearly says that
There is actually a full implementation of alterantive AsyncAPI 2.2.x parser: https://github.com/swagger-api/apidom. It comes with reference implementation of the spec and fully implemented mechanism of resolution and dereferencing. SummaryThis has been the behavior of OpenAPI <= 3.0.x specs. As the AsyncAPI spec was borned from OpenAPI it comes with the same or similar mechanisms. OpenAPI 3.1.x now clearly states that the
|
@char0n thanks for taking the time to provide feedback to the article!
Absolutely, just my own confusion 😄 Don't see the article as anything but the timeline of thoughts as we reflected on the knowledge and tried answering the questions as they came up.
Hmm, I see I haven't formulated myself well enough in the article. One of the points it's missing is a deeper explanation of the schemaFormat. When you define it as However, and this is where I didn't seem to have explained it as when defined as This is also why the bug report to the parser contains an AsyncAPI document with that specific format. This means that technically, parsers have to understand both (
Uhh, nice! Does your parser take into account the different Any reason it is not on the tools list? I see we don't have a section for parsers, but that can be added 😄 However, what I tried to refer to, is core tooling that everyone can use for dereferencing i.e. build their own parsers upon 😄 So implementors don't have to figure out the small details of the specs. |
Right. I missed that the example is based on
We currently support only
Yes I think I got it. The parser I mentioned can semantically parse the spec, has querying capability and provides higher order algorithms like resolution or dereferencing - so consumer can just use it and not deal with complex intricacies of the spec. Bundling is not yet supported as well as |
@char0n would be great if we could all use an underlying library that resolves references for us, so regardless of how specs define the behavior it can adapt it internally instead of being static. But yea, out of scope for this issue 😆 |
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 ❤️ |
@jonaslagoni can we close this one if favor of #829? |
As I understand #829 is only for figuring out if we go with $ref or name for example referencing servers in channels. But honestly, I don't see this as an issue anymore, and the suggestions are kinda useless tbh as there are no use-cases behind it (and the suggestion I made does not really make sense), just confusion based on the parser implementation. Closing. |
The problem
There is a large discrepancy between when a
$ref
can be used in the specification.The current structure kinda makes sense if we assume that all the referenced must be within the very same document, or at least reference an AsyncAPI document variant (referencing to a component). The problem is
$ref
could reference an external file that, if seen in isolation, has nothing to do with AsyncAPI. And it is not until it is bundled together that it forms a valid AsyncAPI document.Example:
The example above is currently not supported in the spec, our JS-parser however incorrectly allows such behavior (which does not help with the confusion).
Here is a list of the immediate problems I found in the spec:
info
) cannot be referencedWays to address it
I see a couple of ways we can address this, the following explains those suggested solutions:
Allow reference anywhere
One option could be to uniform references in such a way that the Reference Object is allowed within any keyword of the specification.
Allow references within any JSON object
Another option would be to allow the Reference Object to be used anywhere a JSON object is expected.
My suggestion
I suggest that we go with the second suggestion, allowing references anywhere a JSON object is expected.
Related issues
The text was updated successfully, but these errors were encountered: