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

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 https://github.com/OAI/OpenAPI-Specification/issues/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.

[JamesMessinger]

Thank you so much for all the detailed information! Sounds like I have a lot of work ahead of me, but I like the direction that JSON Schema and OpenAPI are heading 👍

[Relequestual]

clicks links reads rest of comment Oh 😅