Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 14 additions & 41 deletions specs/jsonschema-core.md
Original file line number Diff line number Diff line change
Expand Up @@ -874,21 +874,14 @@ define new keywords that begin with `$`.

### 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. (See {{compound-validation}} for information on
validating schemas which contain embedded schema resources that declare a
different meta-schema.) The syntax described for a given keyword is expected to
be compatible with the document which defines the keyword; while it is possible
to describe an incompatible syntax, such a meta-schema would be unlikely to be
useful.

Meta-schema authoring is an advanced usage of JSON Schema, so the design of
meta-schema features emphasizes flexibility over simplicity.
A meta-schema is a schema that describes the valid syntax for a JSON Schema.
Meta-schemas can be used by implementations to verify that a schema can be
processed by that implementation. They can also be used by developer tooling to
ensure that all schemas in a project are compatible with a specific JSON Schema
release.[^15]

[^15]: See {{compound-validation}} for information on validating schemas which
contain embedded schema resources that declare a different meta-schema.

#### Dialect Determination

Expand Down Expand Up @@ -923,12 +916,10 @@ MUST refuse to process the schema.

#### The `$schema` Keyword {#keyword-schema}

The `$schema` keyword is both used as a JSON Schema dialect identifier and as
the identifier of a resource which is itself a JSON Schema, which describes the
set of valid schemas written for this particular dialect. The identified dialect
applies to the resource in which it is declared as well as any embedded schema
resources, unless such a resource itself declares a different dialect by
including the `$schema` keyword with a different value.
The `$schema` keyword is used as a JSON Schema dialect identifier. The
identified dialect applies to the resource in which it is declared as well as
any embedded schema resources, unless such a resource itself declares a
different dialect by including the `$schema` keyword with a different value.

The value of this keyword MUST be an
[absolute IRI](https://www.rfc-editor.org/info/rfc3987) (without a fragment).
Expand Down Expand Up @@ -1207,24 +1198,6 @@ disabled by default to prefer offline operation. When schemas are downloaded,
for example by a generic user-agent that does not know until runtime which
schemas to download, see {{hypermedia}}.

#### 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 that a single schema document might sometimes be considered a regular
schema, and other times be considered a meta-schema.

In the case of examining a schema which is its own meta-schema, when an
implementation begins processing it as a regular schema, it is processed under
those rules. However, when loaded a second time as a result of checking its own
`$schema` value, it is treated as a meta-schema. So the same document is
processed both ways in the course of one session.

Implementations MAY allow a schema to be explicitly passed as a meta-schema, for
implementation-specific purposes, such as pre-loading a commonly used
meta-schema and checking its requirements up front. Meta-schema authors MUST NOT
expect such features to be interoperable across implementations.

### Dereferencing

Schemas can be identified by any IRI that has been given to them, including a
Expand Down Expand Up @@ -2317,7 +2290,7 @@ and only allows the "data" and "children" properties. An example instance with

```jsonschema "Tree schema, extensible"
{
"$schema": "https://json-schema.org/v1/2026",
"$schema": "https://json-schema.org/v1",
"$id": "https://example.com/tree",
"$dynamicAnchor": "node",

Expand All @@ -2336,7 +2309,7 @@ and only allows the "data" and "children" properties. An example instance with

```jsonschema "Strict-tree schema, guards against misspelled properties"
{
"$schema": "https://json-schema.org/v1/2026",
"$schema": "https://json-schema.org/v1",
"$id": "https://example.com/strict-tree",
"$dynamicAnchor": "node",

Expand Down
19 changes: 10 additions & 9 deletions specs/jsonschema-validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,12 +102,13 @@ specification.

## Meta-Schema {#meta-schema}

The current IRI for the default JSON Schema dialect meta-schema is
`https://json-schema.org/v1/2026`. This IRI encodes the specification's version
and release year. Because all schemas written to conform to a given version are
guaranteed to be compatible with later releases within the same version, the
meta-schema IRI `https://json-schema.org/v1` is also recognized to represent the
latest release within the indicated version.
The current IRI for the default JSON Schema dialect is
`https://json-schema.org/v1`. The current IRI for the meta-schema for this
dialect is `https://json-schema.org/v1/2026`. This IRI encodes the
specification's version and release year. Because all schemas written to conform
to a given version are guaranteed to be compatible with later releases within
the same version, implementations MAY configure the the dialect IRI to identify
the meta-schema for the latest release within the indicated version.

The meta-schema describes a dialect consisting of all keywords defined in this
specification and the JSON Schema Core specification. Certain keywords specify
Expand All @@ -119,9 +120,9 @@ Schema Core specification, the specifications take precedence, and the
meta-schema is to be considered in error. The meta-schema may be occasionally
updated to correct any such errors.

Although the IRI for the default JSON Schema dialect meta-schema is also a valid
URL, implementations MUST NOT assume that a document is provided at this
location. Rather than performing a network request to retrieve the meta-schema,
Although the IRI for the JSON Schema dialect meta-schema is also a valid URL,
implementations MUST NOT assume that a document is provided at this location.
Rather than performing a network request to retrieve the meta-schema,
implementations SHOULD include a copy of the meta-schema and MAY encode it as
required by the language or framework used by the implementation.

Expand Down
Loading