diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 3154ae5e..d60c5fdf 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -415,6 +415,16 @@ keywords MUST NOT begin with this prefix. Implementations MUST refuse to evaluate schemas which contain keywords which they do not know how to process or explicitly choose not to process. +## Specification Versioning and Compatibility + +This specification is identified collectively by two values: version and release +year. + +A schema written to conform with the requirements of a given version is +compatible with successive specifications, which are published with the same +version and either the same or greater release year value. Thus, JSON Schema +provides a guarantee of compatibility for future releases within a version. + ## Keyword Behaviors JSON Schema keywords fall into several general behavior categories. Assertions @@ -821,16 +831,17 @@ default to using the current location if a default is desireable. ## The JSON Schema Core Keywords {#core} -Keywords declared in this section, which all begin with "$", are essential to -processing JSON Schema. These keywords inform implementations how to process any -schema or meta-schema, including those split across multiple documents, or exist -to reserve keywords for purposes that require guaranteed interoperability. +Keywords declared in this section, which all begin with a dollar sign (`$`), are +essential to processing JSON Schema. These keywords inform implementations how +to process any schema or meta-schema, including those split across multiple +documents, or exist to reserve keywords for purposes that require guaranteed +interoperability. Support for these keywords MUST be considered mandatory at all times as they are necessary to navigate and process any schema. -The "$" prefix is reserved for use by this specification. Extensions MUST NOT -define new keywords that begin with "$". +The `$` prefix is reserved for use by this specification. Extensions MUST NOT +define new keywords that begin with `$`. ### Meta-Schemas @@ -2188,7 +2199,7 @@ and only allows the "data" and "children" properties. An example instance with ```jsonschema "Tree schema, extensible" { - "$schema": "https://json-schema.org/draft/next/schema", + "$schema": "https://json-schema.org/1/2025", "$id": "https://example.com/tree", "$dynamicAnchor": "node", @@ -2207,7 +2218,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/draft/next/schema", + "$schema": "https://json-schema.org/1/2025", "$id": "https://example.com/strict-tree", "$dynamicAnchor": "node", diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 3f43797c..7db17ae8 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -88,16 +88,27 @@ specification. ## Meta-Schema {#meta-schema} The current IRI for the default JSON Schema dialect meta-schema is -`https://json-schema.org/draft/next/schema`. For schema author convenience, this -meta-schema describes a dialect consisting of all keywords defined in this +`https://json-schema.org/1/2025`. 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/1` is also recognized to represent 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 some functionality which is optional to support and is explained in detail in the relevant sections. -Updated meta-schema IRIs MAY be published between specification drafts in order -to correct errors. Implementations SHOULD consider IRIs dated after this -specification draft and before the next to indicate the same syntax and -semantics as those listed here. +Where the meta-schema conflicts with either this specification or the JSON +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, +implementations SHOULD include a copy of the meta-schema and MAY encode it as +required by the language or framework used by the implementation. ## Keywords for Structural Validation