Base URI of external files? (more $id and $anchor fun with $ref resolution)

[handrews]

I never got an answer to this question from #2092 ($id scope resolution):

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, and the file's base URI is distinct from the primary OAS document file)?

Regarding $id and particularly $anchor, this also impacts how something like {"$ref": "#foo"} is resolved. In the main file you might have:

components:
  schemas:
    fooSchema:
      $anchor: foo
      type: object
      properties: {...}
    barSchema:
      type: object
      properties:
        someFoo: {$ref: "#foo"}

In this example, the someFoo property of the barSchema schema references the fooSchema schema using the fragment created by $anchor. That fragment is attached to the base URI for the overall OAS file, so the same question about #/components/schemas/fooSchema from a separate file exists for #foo from a separate file.

@OAI/tsc

[darrelmiller]

What does document mean? That is the question.

[MikeRalphson]

For v3.0 we got away without rewriting https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md - I think for v3.1 we will need to provide guidance, even if most of it is links back to the relevant parts of the JSON Schema spec.

[handrews]

@MikeRalphson I agree, and I can work on that. It will be a separate PR. Should it also be a separate issue? I'd say yes if there needs to be discussion on it.

[handrews]

@darrelmiller was I supposed to wait on another PR closing for this? I remember that coming up on the call but for some reason I didn't make a note of it.

[darrelmiller]

@handrews In the TSC call today we (or some of us) believe that this was resolved in the changes that were made in the relative references text in 3.1. To summarize, relative references are resolved either based on $Id or the location of the resource.
Also, Mike's PR related to option paths clarifies that an OpenAPI document is "composite thing" and not necessarily a physical file.
We are going to merge the changes into rc0 and then re-review this issue holistically.

[handrews]

@darrelmiller that sounds good. My recollection is that folks understood that having a $ref change behavior based on the conceptual OAS doc that its file was included in at that moment is a problem, and that's the main point. Anything that gets clarity on that without tossing RFC 3986 reference resolution out the window is fine with me.