Purpose
This document describes the development and publication process for the JSON Schema specifications:- JSON Schema Core
- JSON Schema Validation
Release and Version
The JSON Schema specification aims to publish annually on or about the First of January each year. Releases are identified by the year they are published. When a new release contains breaking changes, that release begins a new version of JSON Schema. The version is identified as an integer, starting with1 and incrementing as needed.
Stability is prioritized when making changes to the specification. Breaking changes are undesired and should be avoided when possible.
Key Concepts
Defined Behavior
Some behaviors within JSON Schema may be explicitly or implicitly undefined by the specifications for various reasons. How to handle these behaviors is generally left to implementations.- Defined behavior: One that is fully and unambiguously defined by the specifications
- Undefined behavior: Has an “indeterminate” validation result since implementations may resolve the behavior in different ways
Stability and Breaking Changes
Stability is defined using the level of compatibility between sequential releases. If all schemas which are written to one release produce the same defined behavior under the following release, then those releases are compatible, and the specification is said to be stable between them. If an existing schema under the new release exhibits defined behavior that is contrary to defined behavior under the previous release, the new release is said to contain breaking changes and the specification is unstable between those releases. If a new release fully defines a previously undefined (or under-defined) behavior, the new release is still considered compatible, even if it contradicts the decision of any particular implementation.Compatibility Matrix
This table shows the validation results of a hypothetical schema and instance across two consecutive releases:| Next ➡️ / Current ⬇️ | pass | fail | indeterminate |
|---|---|---|---|
| pass | ✅ | ❌ | ❌ |
| fail | ❌ | ✅ | ❌ |
| indeterminate | ✅ | ✅ | ✅ |
Publication
Specifications
The specifications are published on the JSON Schema website athttps://json-schema.org/, using a path comprised of the version, year, and document name. For example:
https://json-schema.org/v1/2026/core.htmlhttps://json-schema.org/v1/2026/validation.html
Meta-schemas
A release meta-schema is published under the same path usingschema.json as the file name:
https://json-schema.org/v1/2026/schema.json
- Serve the meta-schema from its release folder:
https://json-schema.org/v1/2026/ - Serve the meta-schema for the latest release in a version from its version folder:
https://json-schema.org/v1/
These are only publication and availability URLs. The specification defines the
$id values for the meta-schemas.