From c3f8ce7efa56ef2bcc1d039acb5a63d510221448 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 4 Mar 2025 18:26:47 +1300 Subject: [PATCH 1/6] dollar sign has markdown significance --- specs/jsonschema-core.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 3154ae5e..34b65941 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -821,16 +821,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 From 5f9afd70dce3fa678d3a67447cd3570502083f66 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 9 Mar 2025 12:37:43 +1300 Subject: [PATCH 2/6] pushing to back up --- specs/jsonschema-core.md | 6 ++++++ specs/jsonschema-validation.md | 27 +++++++++++++++++++++------ 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 34b65941..46cbe04f 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -415,6 +415,12 @@ 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 versioned by two values: iteration and release year. + +A schema written to conform with the requirements of a given version (iteration and release year) is compatible with specifications published with the same iteration value and either the same or greater release year value. Thus, JSON Schema provides a guarantee of compatibility for future releases within an iteration. + ## Keyword Behaviors JSON Schema keywords fall into several general behavior categories. Assertions diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 3f43797c..dae74e5b 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -88,16 +88,31 @@ 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 specifications iteration +value and release year. Because all schemas written to conform to a given +version are guaranteed to be compatible with later releases within the same +iteration, the meta-schema IRI `https://json-schema.org/1` is also recognized to +represent the latest release within the indicated iteration. + +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. + +## Specification Versioning + +The meta-schema IRI format encodes two values that will assist users in determining compatibiility between releases of the JSON Schema specifications. ## Keywords for Structural Validation From 39d784b49d8aff8306a44e0f6729328a9453571c Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 12 Apr 2025 22:26:14 +1200 Subject: [PATCH 3/6] update other meta-schema iris --- specs/jsonschema-core.md | 4 ++-- specs/jsonschema-validation.md | 14 +++++--------- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 46cbe04f..b7992991 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -2195,7 +2195,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", @@ -2214,7 +2214,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 dae74e5b..04b55111 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -88,11 +88,11 @@ specification. ## Meta-Schema {#meta-schema} The current IRI for the default JSON Schema dialect meta-schema is -`https://json-schema.org/1/2025`. This IRI encodes the specifications iteration -value and release year. Because all schemas written to conform to a given -version are guaranteed to be compatible with later releases within the same -iteration, the meta-schema IRI `https://json-schema.org/1` is also recognized to -represent the latest release within the indicated iteration. +`https://json-schema.org/1/2025`. This IRI encodes the specifications 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 iteration, the +meta-schema IRI `https://json-schema.org/1` is also recognized to represent the +latest release within the indicated iteration. The meta-schema describes a dialect consisting of all keywords defined in this specification and the JSON Schema Core specification. Certain keywords specify @@ -110,10 +110,6 @@ 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. -## Specification Versioning - -The meta-schema IRI format encodes two values that will assist users in determining compatibiility between releases of the JSON Schema specifications. - ## Keywords for Structural Validation Validation keywords in a schema impose requirements for successful validation of From cc9fec3420f46ed26d6066503e596c090b6dcdf1 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 16 Apr 2025 18:32:24 +1200 Subject: [PATCH 4/6] Update specs/jsonschema-validation.md Co-authored-by: Jason Desrosiers --- specs/jsonschema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 04b55111..d1031012 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -88,7 +88,7 @@ specification. ## Meta-Schema {#meta-schema} The current IRI for the default JSON Schema dialect meta-schema is -`https://json-schema.org/1/2025`. This IRI encodes the specifications version +`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 iteration, the meta-schema IRI `https://json-schema.org/1` is also recognized to represent the From 26e37206965b403d9ee451e434fd2a295f1c1670 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 16 Apr 2025 18:51:10 +1200 Subject: [PATCH 5/6] replace 'iteration' language --- specs/jsonschema-core.md | 8 ++++++-- specs/jsonschema-validation.md | 4 ++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index b7992991..d60c5fdf 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -417,9 +417,13 @@ they do not know how to process or explicitly choose not to process. ## Specification Versioning and Compatibility -This specification is versioned by two values: iteration and release year. +This specification is identified collectively by two values: version and release +year. -A schema written to conform with the requirements of a given version (iteration and release year) is compatible with specifications published with the same iteration value and either the same or greater release year value. Thus, JSON Schema provides a guarantee of compatibility for future releases within an iteration. +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 diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index d1031012..7db17ae8 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -90,9 +90,9 @@ specification. The current IRI for the default JSON Schema dialect meta-schema is `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 iteration, the +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 iteration. +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 From 994d8607d73da3f491be0a247f6b905073186af5 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 26 Apr 2025 21:52:38 +1200 Subject: [PATCH 6/6] use "release" Co-authored-by: Jason Desrosiers --- specs/jsonschema-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index d60c5fdf..bf6254c3 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -420,7 +420,7 @@ they do not know how to process or explicitly choose not to process. 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 +A schema written to conform with the requirements of a given release 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.