Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

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

See original GitHub issue

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": ""
  • $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., 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 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:open
  • Created 4 years ago
  • Reactions:7
  • Comments:8 (5 by maintainers)

github_iconTop GitHub Comments

JamesMessingercommented, Jan 18, 2020

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 👍

Relequestualcommented, Jan 18, 2021

clicks links reads rest of comment Oh 😅

Read more comments on GitHub >

github_iconTop 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 >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found