formalize reference locations in the OpenAPI document schema

[karenetheridge]

In my implementation I take note of the reference location of various entities while parsing an openapi document -- e.g. when following a $ref in the schema that points to #/$defs/parameter-or-reference I make a note of the data location (in the openapi document being parsed) that this is a location of a parameter entity. This builds up a registry of location -> entity type maps, which I make use of at runtime when resolving a $ref in the openapi document -- e.g. when validating an HTTP request against the openapi description, and I am processing a parameter object in the description, if I see a $ref to something that I expect is a parameter object, when resolving this reference I check in the entity registry to confirm that the target of the reference is indeed a parameter (and if not, this constitutes a runtime error). [I also have plans to check all $ref targets at parse time, at least for those pointing to the local document, as part of an extra linting step, but haven't implemented this yet.]

This means I am dependent on the name of the references in the openapi schema. Everything is using the same naming convention of #/$defs/foo-or-reference and #/$defs/foo in the schema definitions, but theoretically this could change at any time as there are no guarantees as to how the schema is constructed. Therefore it would be useful to formalize some of these locations and use $anchors in these definitions, and make use of the plain-name fragment form in the $refs, and document their use, so we are free to move things around in the schema while still preserving a name that can be relied upon by implementors.

ref. https://open-api.slack.com/archives/C06A0RPNPGE/p1734458650755389

[handrews]

For folks less familiar with JSON Schema, heres how it looks in the two relevant drafts:

For OAS 3.1):

$schema: https://json-schema.org/draft/2020-12/schema
$defs:
  path-item:
    $anchor: PathItem

For OAS 3.0:

$schema: "https://json-schema.org/draft-04/schema#"
definitions:
  PathItem:
    id: "#PathItem"

Note that the JSON Pointers are different in the two schemas (partially definitions vs defs, but the definition name is a different style in each for reasons unkonwn to me). The draft-04 id and the 2020-12 $anchor both allow this to be referenced with a plain name fragment #PathItem, which would become the public interface.