From bbe7e3373aa98f395ee8135d77634bd7c9139455 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 3 Jun 2026 11:12:46 -0700 Subject: [PATCH 1/2] Update dialect and meta-schema IRI semantics for v1 --- specs/jsonschema-core.md | 32 ++++++-------------------------- specs/jsonschema-validation.md | 19 ++++++++++--------- 2 files changed, 16 insertions(+), 35 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index fefbcf58..e704645b 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -923,12 +923,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). @@ -1207,24 +1205,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 @@ -2317,7 +2297,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", @@ -2336,7 +2316,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", diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 487eb844..ac3aa895 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -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 @@ -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. From 5222266bc7f206564fd8252fc859753f7dd56df5 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 3 Jun 2026 14:12:36 -0700 Subject: [PATCH 2/2] Update the meta-schema section These changes appear to have gotten lost, so here's trying again. --- specs/jsonschema-core.md | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index e704645b..487bad33 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -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