diff --git a/specs/jsonschema-core.md b/specs/jsonschema-core.md index 0670e2a7..e555288a 100644 --- a/specs/jsonschema-core.md +++ b/specs/jsonschema-core.md @@ -410,20 +410,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 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" +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 @@ -564,11 +581,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 @@ -993,21 +1010,22 @@ 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 a 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 +default to operating offline. ##### Dynamic References with `$dynamicRef` {#dynamic-ref} The `$dynamicRef` keyword is an applicator that allows for deferring the full resolution until runtime, at which point it is resolved each time it is -encountered while evaluating an instance. +encountered while evaluating an instance. Its results are the results of the +referenced schema. Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension mechanism that is primarily useful to to create open schemas, where @@ -1465,8 +1483,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} @@ -1727,8 +1745,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` @@ -1737,8 +1755,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 f20f64b2..1174f1ff 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 evaluation 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 @@ -614,7 +629,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