From de8ed3004a4e39b54b8a9d2d8bc546c6c5521573 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 19 Jan 2025 20:18:03 +1300 Subject: [PATCH 1/9] keywords only exhibit the behaviors they're defined with --- specs/jsonschema-core.md | 58 +++++++++++++++++++++++----------- specs/jsonschema-validation.md | 17 +++++++++- 2 files changed, 56 insertions(+), 19 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 3154ae5e..74244c86 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -415,20 +415,37 @@ 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. -## Keyword Behaviors +## Keyword Behaviors {#keyword-behaviors} -JSON Schema keywords fall into several general behavior categories. Assertions -validate that an instance satisfies constraints, producing a boolean result. -Annotations attach information that applications may use in any way they see -fit. Applicators apply subschemas to parts of the instance and combine their -results. +JSON Schema keywords may exhibit one or more behaviors. This specification +defines three such behaviors: + +- Assertions validate that an instance satisfies constraints, producing a + boolean result: `true` if the constraints are satisfied; `false` otherwise. +- Annotations attach information that applications may use in any way they see + fit. +- Applicators apply subschemas to parts of the instance and combine their + results. -Extension keywords SHOULD stay within these categories, keeping in mind that +Extension keywords SHOULD be defined using these behaviors, keeping in mind that annotations in particular are extremely flexible. Complex behavior is usually better delegated to applications on the basis of annotation data than implemented directly as schema keywords. However, extension keywords MAY define other behaviors for specialized purposes. +Keywords which are not defined to exhibit a particular behavior MUST NOT affect +that aspect of evalution. For example, a keyword which does not act as an +assertion MUST NOT affect the validation result. + +For the purposes of this document, an instance "validating against a keyword" +means that the keyword produces an assertion result of `true` if the instance +satisfies the given constraint; otherwise an assertion result of `false` is +produced. + + + Evaluating an instance against a schema involves processing all of the keywords in the schema against the appropriate locations within the instance. Typically, applicator keywords are processed until a schema object with no applicators (and @@ -569,11 +586,11 @@ the keyword's value. Alternatively, an applicator may refer to a schema elsewhere in the same schema document, or in a different one. The mechanism for identifying such referenced schemas is defined by the keyword. -Applicator keywords also define how subschema or referenced schema boolean -[assertion](#assertions) results are modified and/or combined to produce the -boolean result of the applicator. Applicators may apply any boolean logic -operation to the assertion results of subschemas, but MUST NOT introduce new -assertion conditions of their own. +Applicator keywords also behave as assertions by defining how subschema or +referenced schema boolean [assertion](#assertions) results are modified and/or +combined to produce the boolean result of the applicator. Applicators may apply +any boolean logic operation to the assertion results of subschemas, but MUST NOT +introduce new assertion conditions of their own. [Annotation](#annotations) results from subschemas are preserved in accordance with {{collect}} so that applications can decide how to interpret multiple @@ -1001,11 +1018,16 @@ identified schema. Its results are the results of the referenced schema.[^5] [^5]: Note that this definition of how the results are determined means that other keywords can appear alongside of `$ref` in the same schema object. +The value of the `$ref` keyword MUST be a string which is an IRI reference. The value of the `$ref` keyword MUST be a string which is an IRI reference. Resolved against the current IRI base, it produces the IRI of the schema to apply. This resolution is safe to perform on schema load, as the process of evaluating an instance cannot change how the reference resolves. +The resolved IRI produced by `$ref` is not necessarily a network locator, only +an identifier. A schema need not be downloadable from the address if it is a +network-addressable URL. Implementations which can access the network SHOULD +default to operating offline. The resolved IRI produced by `$ref` is not necessarily a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressable URL. Implementations which can access the network SHOULD @@ -1476,8 +1498,8 @@ operators can contact the owner of a potentially misbehaving script. ## Keywords for Applying Subschemas -This section defines a set of keywords that enable schema combinations and -composition. +This section defines a set of applicator keywords that enable schema +combinations and composition. ### Keywords for Applying Subschemas in Place {#in-place} @@ -1737,8 +1759,8 @@ The value of this keyword MUST be a non-negative integer. This keyword modifies the behavior of `contains` within the same schema object, as described below in the section for that keyword. -Validation MUST always succeed against this keyword. The value of this keyword -is used as its annotation result. +This keyword produces no assertion result. The value of this keyword is used as +its annotation result. ##### `minContains` @@ -1747,8 +1769,8 @@ The value of this keyword MUST be a non-negative integer. This keyword modifies the behavior of `contains` within the same schema object, as described below in the section for that keyword. -Validation MUST always succeed against this keyword. The value of this keyword -is used as its annotation result. +This keyword produces no assertion result. The value of this keyword is used as +its annotation result. Per {{default-behaviors}}, omitted keywords MUST NOT produce annotation results. However, as described in {{contains}}, the absence of this keyword's annotation diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 3f43797c..d81bac1e 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -62,6 +62,21 @@ information. The {{format}} keyword is intended primarily as an annotation, but can optionally be used as an assertion. The {{content}} keywords are annotations for working with documents embedded as JSON strings. +## Keyword Behaviors + +The keywords defined by this document exhibit one or more behaviors as defined by +the [JSON Schema Core Specification](./jsonschema-core.md#keyword-behaviors). + +Keywords which are not defined to exhibit a particular behavior MUST NOT affect +that aspect of the evalution outcome. In particular, the keywords defined in +{{annotations}} produce no assertion result and therefore are not considered +during validation. + +For the purposes of this document, an instance "validating against a keyword" +means that the keyword produces an assertion result of `true` if the instance +satisfies the given constraint; otherwise an assertion result of `false` is +produced. + ## Interoperability Considerations ### Validation of String Instances @@ -642,7 +657,7 @@ structures: first the header, and then the payload. Since the JWT media type ensures that the JWT can be represented in a JSON string, there is no need for further encoding or decoding. -## Keywords for Basic Meta-Data Annotations +## Keywords for Basic Meta-Data Annotations {#annotations} These general-purpose annotation keywords provide commonly used information for documentation and user interface display purposes. They are not intended to form From 2058d3ef64d39b293d5bb1b770f45b94a7fc6e9b Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 2 Feb 2025 13:29:19 +1300 Subject: [PATCH 2/9] Update specs/jsonschema-core.md 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 74244c86..070c27fe 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -434,7 +434,7 @@ implemented directly as schema keywords. However, extension keywords MAY define other behaviors for specialized purposes. Keywords which are not defined to exhibit a particular behavior MUST NOT affect -that aspect of evalution. For example, a keyword which does not act as an +that aspect of evaluation. For example, a keyword which does not act as an assertion MUST NOT affect the validation result. For the purposes of this document, an instance "validating against a keyword" From a695c40d893a64724ef17dcfa2726203bb2be5f8 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 2 Feb 2025 13:30:29 +1300 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Jason Desrosiers --- specs/jsonschema-core.md | 2 +- specs/jsonschema-validation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 070c27fe..d35bf66b 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -442,7 +442,7 @@ means that the keyword produces an assertion result of `true` if the instance satisfies the given constraint; otherwise an assertion result of `false` is produced. - diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index d81bac1e..e5a29105 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -68,7 +68,7 @@ The keywords defined by this document exhibit one or more behaviors as defined b the [JSON Schema Core Specification](./jsonschema-core.md#keyword-behaviors). Keywords which are not defined to exhibit a particular behavior MUST NOT affect -that aspect of the evalution outcome. In particular, the keywords defined in +that aspect of the evaluation outcome. In particular, the keywords defined in {{annotations}} produce no assertion result and therefore are not considered during validation. From 1a7a34af7c2f8607bef67bc0569494e06dfa9753 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 12 Apr 2025 13:09:47 +1200 Subject: [PATCH 4/9] added some notes to add context --- specs/jsonschema-core.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index d35bf66b..110cf326 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -418,7 +418,7 @@ they do not know how to process or explicitly choose not to process. ## Keyword Behaviors {#keyword-behaviors} JSON Schema keywords may exhibit one or more behaviors. This specification -defines three such behaviors: +defines three such behaviors[^7]: - Assertions validate that an instance satisfies constraints, producing a boolean result: `true` if the constraints are satisfied; `false` otherwise. @@ -427,6 +427,12 @@ defines three such behaviors: - Applicators apply subschemas to parts of the instance and combine their results. +[^7]: This specification also defines several operational directive keywords, +such as `$id` and `$schema`. As such, these keywords do not exhibit these +behaviors. However, it is recommended that extensions avoid defining additional +directive keywords as they could interfere with schema processing and produce +unexpected or undesirable results. + Extension keywords SHOULD be defined using these behaviors, keeping in mind that annotations in particular are extremely flexible. Complex behavior is usually better delegated to applications on the basis of annotation data than @@ -589,8 +595,14 @@ identifying such referenced schemas is defined by the keyword. Applicator keywords also behave as assertions by defining how subschema or referenced schema boolean [assertion](#assertions) results are modified and/or combined to produce the boolean result of the applicator. Applicators may apply -any boolean logic operation to the assertion results of subschemas, but MUST NOT -introduce new assertion conditions of their own. +any boolean logic operation to the assertion results of subschemas, but SHOULD +NOT introduce new assertion conditions of their own.[^2] + +[^2]: It is recommended that keywords have a single resposibility. An example of +this in action is the separation between `properties`, which verifies object +property values have the right data _if_ they exist, and `required`, which +verifies that object properties exist. Separating these concerns allows for more +reusable components. [Annotation](#annotations) results from subschemas are preserved in accordance with {{collect}} so that applications can decide how to interpret multiple From 50e9aca23cdfae3146ab2cbe41345a32102e9ea8 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 16 Apr 2025 20:37:14 +1200 Subject: [PATCH 5/9] be more specific on annotation targets 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 110cf326..a4f9c8f6 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -422,7 +422,7 @@ defines three such behaviors[^7]: - Assertions validate that an instance satisfies constraints, producing a boolean result: `true` if the constraints are satisfied; `false` otherwise. -- Annotations attach information that applications may use in any way they see +- Annotations attach information to instance locations that applications may use in any way they see fit. - Applicators apply subschemas to parts of the instance and combine their results. From b48cf7129bbfa2240c2037ce00a61cee1357acb0 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 19 Apr 2025 16:33:18 +1200 Subject: [PATCH 6/9] revisit 'directive' behaviors text; add requirement about extensions redefining keywords --- specs/jsonschema-core.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index a4f9c8f6..9fe2be79 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -394,6 +394,18 @@ Additional schema keywords MAY be defined by any entity. Save for explicit agreement, schema authors SHALL NOT expect these additional keywords to be supported by implementations that do not explicitly document such support. +Extension keywords MUST NOT interfere with the operation of keywords defined by +this document or the companion JSON Schema Validation specificiation, and SHOULD +NOT interfere with the operation of keywords defined by other extension +documents.[^11] + +[^11]: JSON Schema currently does not have a namespacing mechanism, which would +allow multiple extensions to define the same keyword differently while also +giving the schema author the ability to declare which definition is intended. +Such a feature is planned for future releases. See the +[Vocabularies / Extensions project](https://github.com/orgs/json-schema-org/projects/28/views/2) +in GitHub for more information. + Implementations MAY provide the ability to register or load handlers for keywords that they do not support directly. The exact mechanism for registering and implementing such handlers is implementation-dependent. @@ -422,16 +434,15 @@ defines three such behaviors[^7]: - Assertions validate that an instance satisfies constraints, producing a boolean result: `true` if the constraints are satisfied; `false` otherwise. -- Annotations attach information to instance locations that applications may use in any way they see - fit. +- Annotations attach information to instance locations that applications may use + in any way they see fit. - Applicators apply subschemas to parts of the instance and combine their results. [^7]: This specification also defines several operational directive keywords, -such as `$id` and `$schema`. As such, these keywords do not exhibit these -behaviors. However, it is recommended that extensions avoid defining additional -directive keywords as they could interfere with schema processing and produce -unexpected or undesirable results. +such as `$id` and `$schema`, which do not exhibit these behaviors. Instead, +these keywords provide metadata that instruct implementations on how to +interpret and process the schema. Extension keywords SHOULD be defined using these behaviors, keeping in mind that annotations in particular are extremely flexible. Complex behavior is usually @@ -439,9 +450,7 @@ better delegated to applications on the basis of annotation data than implemented directly as schema keywords. However, extension keywords MAY define other behaviors for specialized purposes. -Keywords which are not defined to exhibit a particular behavior MUST NOT affect -that aspect of evaluation. For example, a keyword which does not act as an -assertion MUST NOT affect the validation result. +Implementations SHOULD NOT add unspecified behaviors to keywords. For the purposes of this document, an instance "validating against a keyword" means that the keyword produces an assertion result of `true` if the instance From 78ca35dede021e63f3b7df3ce3d502ce289ab736 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 23 Apr 2025 10:04:35 +1200 Subject: [PATCH 7/9] remove duplicate text Co-authored-by: Jason Desrosiers --- specs/jsonschema-core.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 9fe2be79..c9042461 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1039,16 +1039,11 @@ identified schema. Its results are the results of the referenced schema.[^5] [^5]: Note that this definition of how the results are determined means that other keywords can appear alongside of `$ref` in the same schema object. -The value of the `$ref` keyword MUST be a string which is an IRI reference. The value of the `$ref` keyword MUST be a string which is an IRI reference. Resolved against the current IRI base, it produces the IRI of the schema to apply. This resolution is safe to perform on schema load, as the process of evaluating an instance cannot change how the reference resolves. -The resolved IRI produced by `$ref` is not necessarily a network locator, only -an identifier. A schema need not be downloadable from the address if it is a -network-addressable URL. Implementations which can access the network SHOULD -default to operating offline. The resolved IRI produced by `$ref` is not necessarily a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressable URL. Implementations which can access the network SHOULD From 20fe3e129c97140bf26110f0b38ebb50e31490e0 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 26 Apr 2025 20:27:47 +1200 Subject: [PATCH 8/9] use behavior language 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 c9042461..77a4c2e2 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -1785,7 +1785,7 @@ The value of this keyword MUST be a non-negative integer. This keyword modifies the behavior of `contains` within the same schema object, as described below in the section for that keyword. -This keyword produces no assertion result. The value of this keyword is used as +This keyword has no assertion behavior. The value of this keyword is used as its annotation result. Per {{default-behaviors}}, omitted keywords MUST NOT produce annotation results. From 784ad8b25790db99cda76b61c7159c2f2e83debc Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 26 Apr 2025 20:30:32 +1200 Subject: [PATCH 9/9] Clean up applicator assertion language Co-authored-by: Ethan <133719+notEthan@users.noreply.github.com> --- specs/jsonschema-core.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 77a4c2e2..691ecdbd 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -601,9 +601,11 @@ the keyword's value. Alternatively, an applicator may refer to a schema elsewhere in the same schema document, or in a different one. The mechanism for identifying such referenced schemas is defined by the keyword. -Applicator keywords also behave as assertions by defining how subschema or -referenced schema boolean [assertion](#assertions) results are modified and/or -combined to produce the boolean result of the applicator. Applicators may apply +Applicator keywords also behave as assertions, using the assertion results of +each subschema or referenced schema of the keyword. These boolean results are +modified (e.g. the `not` keyword negates its subschema's assertion) and/or +combined (e.g. `allOf` takes the conjunction of its subschemas' assertions) +to produce the boolean result of the applicator. any boolean logic operation to the assertion results of subschemas, but SHOULD NOT introduce new assertion conditions of their own.[^2]