What Is JSON Schema Draft 2024?
JSON Schema is the widely adopted vocabulary for describing and validating JSON document structure. Since its informal beginnings around 2009, it has gone through multiple drafts — draft-04, draft-06, draft-07, 2019-09, 2020-12 — each addressing shortcomings of the previous version. The Draft 2024 release continues this evolution, targeting specific ambiguities that have caused real-world interoperability failures between validator implementations.
Unlike some previous drafts that introduced large structural changes (the vocabulary system in 2020-12, for example), Draft 2024 is a refinement release. Its goal is to close gaps in the specification language that left implementors with conflicting but technically valid interpretations.
Fixing $ref and $defs Ambiguities
The most significant changes in Draft 2024 centre on $ref and $defs. In earlier drafts, the behaviour of $ref alongside sibling keywords was underspecified. Some validators evaluated sibling keywords adjacent to a $ref; others ignored them entirely, treating $ref as a full replacement. Draft 2024 provides explicit normative language resolving this.
Similarly, the relationship between $defs (the standard location for reusable schema definitions) and the root schema boundary has been clarified. A schema that defines recursive types via $defs with $dynamicRef can now be processed consistently by all conforming validators without implementation-specific workarounds.
These fixes are directly traceable to issue reports collected from major validator projects including ajv, jsonschema (Python), and hyperjump. The draft is the first to emerge from the JSON Schema working group's structured issue-triage process on GitHub.
Interoperability Improvements
Beyond $ref, Draft 2024 tightens the specification language around annotation collection and output formatting. JSON Schema 2020-12 introduced a formal output format (basic, detailed, verbose) that validators should produce when validation fails. In practice, different validators produced subtly different output trees for the same schema and instance. Draft 2024 adds normative test vectors that validators must pass to claim conformance.
The draft also addresses edge cases in if/then/else annotation collection, a known pain point where the annotations produced by the if branch were inconsistently reported by implementations when the condition was false.
Getting Started
Draft 2024 schemas declare their dialect with the $schema keyword pointing to the 2024 meta-schema URI (to be published at https://json-schema.org/draft/2024/schema upon finalisation). Schemas targeting 2020-12 will continue to work; the newer dialect is opt-in.
The JSON Schema website maintains a list of implementations and their draft support levels. Before adopting Draft 2024 in production, confirm that your chosen validator has published conformance test results against the new draft.