Skip to content
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

Define the scope of $id resolution #2092

Closed
darrelmiller opened this issue Jan 9, 2020 · 7 comments
Closed

Define the scope of $id resolution #2092

darrelmiller opened this issue Jan 9, 2020 · 7 comments

Comments

@darrelmiller
Copy link
Member

No description provided.

@philsturgeon
Copy link
Contributor

Let's make sure this work solves #2038 too.

@handrews
Copy link
Member

handrews commented Feb 6, 2020

@philsturgeon let's please keep these issues separate. It's not clear that action should be taken on #2038, while the basic work here is straightforward.

@handrews
Copy link
Member

handrews commented Feb 6, 2020

I think part of what needs to happen here is to point to the soon-to-be-consolidated (in the bugfix/clarification draft that will come out in coordination with OAS 3.1) guidance on loading JSON Schemas, and explain how that fits into processing OpenAPI files.

@darrelmiller @webron I seem to recall a reluctance to get too much into OAS file processing, but since JSON Schema processing is defined and has a lot to do with ensuring that $id, $anchor, and $ref function correctly, making sure that it's clear how and when to hand off OAS processing to JSON Schema processing would be helpful.

The main issue is determining the base URI. The relevant part of RFC 3986 and the JSON Schema spec is that in the absence of an %id in the root of the OAS Schema Object, its retrieval URI is used to determine the base.

Since the retrieval URI is <oas-document-base-URI>#/path/to/schemaobject, we probably want to just make clear that that does in fact mean that <oas-document-base-uri> is the base URI in the absence of $id. This is the thing that's already clear if you can recite the RFC3986 base URI determination process in your sleep, but that probably should be called out for everyone else :-)

@handrews
Copy link
Member

handrews commented Feb 6, 2020

We might also want to make sure that it's clear that if your Schema Object does have an $id, relative URI-references in $ref in child schemas cannot do things like "#/components/schemas/foo" because that would go relative to the $id and not to the OAS document as a whole.

If you are using a Schema Object with a $id, then you need to write you relative references the same as if the Schema Object were a separate file/resource at that URI. So you'd have to write out <oas-document-base-uri>#/components/schemas/foo in full. Or possibly some path-relative thing, but definitely not a fragment-only thing.

@handrews
Copy link
Member

handrews commented Feb 6, 2020

@webron @darrelmiller if I put a non-Schema Object (like a Response Object) in its own file, what is the base URI for Reference Objects in that file? In particular, is #/components/whatever expected to work (because it is resolved relative to the primary OAS file) or fail (because Response Objects don't have a components property)?

@darrelmiller
Copy link
Member Author

Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
http://spec.openapis.org/oas/v3.0.2#relative-references-in-urls

"current document" means the document the $ref was actual found in, not the root document being processed.

@darrelmiller
Copy link
Member Author

As per the TSC call Feb, 13th, a schema object's $id can be used from any other schema object in the OAS description.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants