Skip to content

"$id" and "$ref" changes in JSON Schema draft 2019-09 and OAS 3.1 #145

Open
@handrews

Description

JSON Schema draft 2019-09 (formerly known as draft-08) introduced several changes around $ref and $id. This draft is being adopted by the OpenAPI Specification version 3.1.

  • The plain-name fragment declaration function of $id was split into a separate keyword, $anchor
    • "$id": "#foo" becomes "$anchor": "foo"
    • note lack of # as the value of $anchor is just the name
    • It is still referenced as "$ref": "#foo" or "$ref": "https://example.com/some-schema#foo"
  • $id itself MUST resolve to an absolute URI (no fragment)
    • Any schema with an $id is therefore a full resource with its own URI, even if embedded in another resource
    • An empty JSON Pointer fragment, e.g. https://example.com/some-schema#, is allowed because it is equivalent to not having a fragment
    • This is also because of historical usage in older meta-schemas
  • $ref can now have other keywords beside it
    • The result of the $ref keyword is simply the result of the reference schema
    • That result is combined with other keyword results in the usual way
    • This means that it is not any sort of merge
    • {"type": "object", "$ref": "foo"} is equivalent to {"type": "object", "allOf": [{... contents of foo schema ...}]}

Since this library has not previously supported "$id": "#foo", if you only support one form I would suggest "$anchor": "foo" since that is where OpenAPI is headed.

See also OAI/OpenAPI-Specification#2092 for further details on how this fits into OAS 3.1, as obviously OAS Reference Objects outside of Schema Objects don't know about allOf, etc.

Feel free to ask questions on the JSON Schema slack. I will also keep an eye on this issue.

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions