Define the scope of $id resolution

[darrelmiller]

No description provided.

[philsturgeon]

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

[handrews]

@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]

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]

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]

@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]

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]

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