Skip to main content

​
Specification Versioning

This specification is identified collectively by two values:
  • Version: Denoted as the letter “v” followed by the version number
  • Release Year: The year the specification was released
For example:
  • “v1/2026” denotes version 1, released in 2026
  • “v2/2042” would denote version 2, released in 2042

​
Compatibility Guarantees

A schema written to conform with the requirements of a given version is compatible with successive specifications that are published with:
  • The same version number
  • The same or greater release year value
JSON Schema provides a guarantee of forward compatibility for future releases within a version.
This means:
  • A schema conforming to v1/2026 will work with v1/2027, v1/2028, etc.
  • A schema conforming to v1/2026 may NOT work with v2/2026
  • Implementations supporting v1/2027 must also support schemas from v1/2026

​
The $schema Keyword

The $schema keyword serves dual purposes:
  1. Dialect identifier: Indicates which JSON Schema dialect the schema conforms to
  2. Meta-schema reference: Points to a resource that is itself a JSON Schema describing the set of valid schemas for this dialect
The value of this keyword MUST be:
  • An IRI (containing a scheme)
  • Normalized according to IRI normalization rules

​
Usage

The $schema keyword SHOULD be used in the document root schema object:
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.json",
  "type": "object"
}
The identified dialect applies to the resource in which it is declared as well as any embedded schema resources, unless such a resource declares a different dialect with its own $schema keyword.

​
Dialect Determination

When evaluation encounters a new schema resource (i.e., the lexical scope changes), the first task is to determine the dialect. Implementations MUST determine the dialect using the following prioritized steps:
1

The $schema keyword

If present, implementations MUST process the schema according to the dialect it declares.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object"
}
2

Parent schema dialect

A schema resource embedded within another schema resource which does not contain a $schema keyword MUST be processed using the same dialect as the schema which contains it.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "myDef": {
      // Inherits draft/2020-12 from parent
      "type": "string"
    }
  }
}
3

External context

In some contexts, there is a default dialect or a way to declare the dialect external from the schema resource:
  • Embedded in non-schema documents: If the schema is embedded in a non-schema document (such as an OpenAPI Document), the semantics for determining the dialect MUST be determined by that document’s specification
  • Media type: If the media type of the schema is known and defines a default dialect or way to declare a dialect, the dialect MUST be determined by the rules of that media type. For example, the application/schema+json media type includes a schema parameter for declaring the dialect
4

User configuration

Implementations MAY provide means for the user to configure the dialect under which a schema should be processed.
If the dialect is not specified through one of these methods, the implementation MUST refuse to process the schema.

​
Meta-Schemas

Meta-schemas are used to inform an implementation how to interpret a schema. Every schema has a meta-schema, which can be explicitly declared using the $schema keyword. The meta-schema serves to describe valid schema syntax. A schema resource MUST successfully validate against its meta-schema, which constrains the syntax of the available keywords.
Meta-schema authoring is an advanced usage of JSON Schema, so the design of meta-schema features emphasizes flexibility over simplicity.

​
Detecting a Meta-Schema

Implementations MUST recognize a schema as a meta-schema if it is being examined because it was identified as such by another schema’s $schema keyword. This means a single schema document might sometimes be:
  • A regular schema
  • A meta-schema (when referenced by another schema’s $schema)
In the case of a schema that is its own meta-schema:
  1. When processing begins, it is processed as a regular schema
  2. When loaded a second time as a result of checking its own $schema value, it is treated as a meta-schema
The same document is processed both ways in the course of one session.

​
Compound Documents and Dialects

When multiple schema resources are present in a single document:

​
Default Dialect Inheritance

Schema resources which do not define with which dialect they should be processed MUST be processed with the same dialect as the enclosing resource: 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/main.json",
  "$defs": {
    "address": {
      "$id": "https://example.com/address.json",
      // Inherits draft/2020-12 from parent
      "type": "object"
    }
  }
}

​
Different Dialects

Embedded schema resources MAY specify different processing dialects using $schema values from their enclosing resource: 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/mixed.json",
  "$defs": {
    "modern": {
      "$id": "https://example.com/modern.json",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object"
    },
    "legacy": {
      "$id": "https://example.com/legacy.json",
      "$schema": "https://json-schema.org/draft-07/schema#",
      "type": "object"
    }
  }
}

​
Validating Compound Documents

Given that a Compound Schema Document may have embedded resources using different dialects:
These documents SHOULD NOT be validated by applying a meta-schema to the Compound Schema Document as an instance.
Instead:
  • Each Schema Resource SHOULD be separately validated against its associated meta-schema
  • An alternate validation process should be provided to validate Schema Documents
Exception: A Compound Schema Document in which all embedded resources identify as using the same dialect, or in which $schema is omitted (and therefore defaults to that of the enclosing resource), MAY be validated by applying the appropriate meta-schema.

​
Future Development

Continued development of these specifications and support requirements for proposed features is managed in the json-schema-org/json-schema-spec GitHub repository and defined by PROCESS.md.

​
Draft Releases

This document obsoletes the previous “draft” releases for JSON Schema and provides the basis for a stable, standardized version. Implementations MAY continue to support “draft” releases to facilitate the transition, typically by inspecting the value of the $schema keyword: 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

​
Common $schema Values

Here are commonly used $schema values: 
https://json-schema.org/draft/2020-12/schema
The most recent draft specification before the stable release. Introduced prefixItems, $dynamicRef, and $dynamicAnchor.
https://json-schema.org/draft/2019-09/schema
Introduced $recursiveRef, $recursiveAnchor, unevaluatedProperties, and unevaluatedItems.
http://json-schema.org/draft-07/schema#
Widely adopted draft. Introduced if/then/else, readOnly, writeOnly, and content keywords.
http://json-schema.org/draft-06/schema#
Introduced const, contains, and propertyNames.

​
Best Practices

Always Specify $schema

Include $schema in your root schema to make the intended dialect explicit

Use Stable Versions

For production schemas, use stable specification versions rather than working drafts

Document Mixed Dialects

If using multiple dialects in a compound document, document why each dialect is used

Test Across Versions

When upgrading to a new version, test your schemas thoroughly for compatibility

​
Next Steps

Core Keywords

Explore the $schema and other core keywords

Schema Structure

Learn about schema resources and composition

Build docs developers (and LLMs) love

Get started for freeTalk to us