From 4412afcce7187cc606be27117d7dbbb752ed2a48 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 4 Mar 2025 18:26:47 +1300 Subject: [PATCH 1/5] 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 04efe9d2..f9367678 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -873,16 +873,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 599449ea445f2e95be21687c0a8ec12cba03cea5 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 9 Mar 2025 12:37:43 +1300 Subject: [PATCH 2/5] 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 f9367678..a7e5b38b 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -427,6 +427,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 {#keyword-behaviors} JSON Schema keywords may exhibit one or more behaviors. This specification diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 234e0884..c853946c 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -103,16 +103,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 784b1793ecedb03b56679bd6a5668c50dabcdcd7 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 12 Apr 2025 22:26:14 +1200 Subject: [PATCH 3/5] 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 a7e5b38b..3286d1a0 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -2250,7 +2250,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", @@ -2269,7 +2269,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 c853946c..f3767d0f 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -103,11 +103,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 @@ -125,10 +125,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 f057ff48203704aa90e9e6508bdaf496f472901e Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 16 Apr 2025 18:32:24 +1200 Subject: [PATCH 4/5] 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 f3767d0f..bb403a68 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -103,7 +103,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 4a5da5f0829c3b06a72e4fd79b1742523e42e0d2 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 16 Apr 2025 18:51:10 +1200 Subject: [PATCH 5/5] 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 3286d1a0..aa77d218 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -429,9 +429,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 {#keyword-behaviors} diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index bb403a68..ab980f88 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -105,9 +105,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