"$id" and "$ref" changes in JSON Schema draft 2019-09 and OAS 3.1
See original GitHub issueIssue 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 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.
Issue Analytics
- State:
- Created 3 years ago
- Reactions:7
- Comments:8 (5 by maintainers)
Top Results From Across the Web
JSON Schema 2019-09 Release Notes
Core Vocabulary # ; $id, changed, Only URI-references without fragments are allowed; see $anchor for a replacement for plain-name fragments; all other fragments ......
Read more >Migrating from OpenAPI 3.0 to 3.1.0
Everything inside the `schema` keyword in OpenAPI is defined by the Schema Object. This has always been loosely based on JSON Schema, ...
Read more >json-schema-ref-parser - Bountysource
"$id" and "$ref" changes in JSON Schema draft 2019-09 and OAS 3.1 $ 0. Created 2 years ago in APIDevTools/json-schema-ref-parser with 7 comments....
Read more >How to define UUID property in JSON Schema and Open API ...
OAS uses several known formats to define in fine detail the data ... in JSON Schema spec version 2019-09 (previously known as draft-08)....
Read more >JSON Schema Bundling Finally Formalised
While the number of changes from JSON Schema draft-04 to draft 2020-12 are ... OAS 3.1 ushering in full JSON Schema support dramatically ......
Read more >
Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free
Top Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
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 👍
clicks links reads rest of comment Oh 😅