"$id" and "$ref" changes in JSON Schema draft 2019-09 and OAS 3.1 #145
Open
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
- Any schema with an
$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 ...}]}
- The result of the
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.