@@ -394,6 +394,18 @@ Additional schema keywords MAY be defined by any entity. Save for explicit
394394agreement, schema authors SHALL NOT expect these additional keywords to be
395395supported by implementations that do not explicitly document such support.
396396
397+ Extension keywords MUST NOT directly modify the operation of keywords defined by
398+ this document or the companion JSON Schema Validation specificiation, and SHOULD
399+ NOT directly modify the operation of keywords defined by other extension
400+ documents.[ ^ 11 ]
401+ 402+ [ ^ 11 ] : JSON Schema currently does not have a namespacing mechanism, which would
403+ allow multiple extensions to define the same keyword differently while also
404+ giving the schema author the ability to declare which definition is intended.
405+ Such a feature is planned for future releases. See the
406+ [ Vocabularies / Extensions project] ( https://github.com/orgs/json-schema-org/projects/28/views/2 )
407+ in GitHub for more information.
408+ 397409Implementations MAY provide the ability to register or load handlers for
398410keywords that they do not support directly. The exact mechanism for registering
399411and implementing such handlers is implementation-dependent.
@@ -415,20 +427,40 @@ keywords MUST NOT begin with this prefix.
415427Implementations MUST refuse to evaluate schemas which contain keywords which
416428they do not know how to process or explicitly choose not to process.
417429
418- ## Keyword Behaviors
430+ ## Keyword Behaviors {#keyword-behaviors}
419431
420- JSON Schema keywords fall into several general behavior categories. Assertions
421- validate that an instance satisfies constraints, producing a boolean result.
422- Annotations attach information that applications may use in any way they see
423- fit. Applicators apply subschemas to parts of the instance and combine their
424- results.
432+ JSON Schema keywords may exhibit one or more behaviors. This specification
433+ defines three such behaviors[ ^ 7 ] :
434+ 435+ - Assertions validate that an instance satisfies constraints, producing a
436+ boolean result: ` true ` if the constraints are satisfied; ` false ` otherwise.
437+ - Annotations attach information to instance locations that applications may use
438+ in any way they see fit.
439+ - Applicators apply subschemas to parts of the instance and combine their
440+ results.
441+ 442+ [ ^ 7 ] : This specification also defines several operational directive keywords,
443+ such as ` $id ` and ` $schema ` , which do not exhibit these behaviors. Instead,
444+ these keywords provide metadata that instruct implementations on how to
445+ interpret and process the schema.
425446
426- Extension keywords SHOULD stay within these categories , keeping in mind that
447+ Extension keywords SHOULD be defined using these behaviors , keeping in mind that
427448annotations in particular are extremely flexible. Complex behavior is usually
428449better delegated to applications on the basis of annotation data than
429450implemented directly as schema keywords. However, extension keywords MAY define
430451other behaviors for specialized purposes.
431452
453+ Implementations SHOULD NOT add unspecified behaviors to keywords.
454+ 455+ For the purposes of this document, an instance "validating against a keyword"
456+ means that the keyword produces an assertion result of ` true ` if the instance
457+ satisfies the given constraint; otherwise an assertion result of ` false ` is
458+ produced.
459+ 460+ <!-- The next two paragraphs and the following section seem to have more to
461+ do with schema evaluation than keywords specifically. I'd like to move them out
462+ of the "keyword behaviors" h2, but will do so separately. [TODO: GD] -->
463+ 432464Evaluating an instance against a schema involves processing all of the keywords
433465in the schema against the appropriate locations within the instance. Typically,
434466applicator keywords are processed until a schema object with no applicators (and
@@ -581,11 +613,19 @@ the keyword's value. Alternatively, an applicator may refer to a schema
581613elsewhere in the same schema document, or in a different one. The mechanism for
582614identifying such referenced schemas is defined by the keyword.
583615
584- Applicator keywords also define how subschema or referenced schema boolean
585- [ assertion] ( #assertions ) results are modified and/or combined to produce the
586- boolean result of the applicator. Applicators may apply any boolean logic
587- operation to the assertion results of subschemas, but MUST NOT introduce new
588- assertion conditions of their own.
616+ Applicator keywords also behave as assertions, using the assertion results of
617+ each subschema or referenced schema of the keyword. These boolean results are
618+ modified (e.g. the ` not ` keyword negates its subschema's assertion) and/or
619+ combined (e.g. ` allOf ` takes the conjunction of its subschemas' assertions) to
620+ produce the boolean result of the applicator. Applicators may apply any boolean
621+ logic operation to the assertion results of subschemas, but SHOULD NOT introduce
622+ new assertion conditions of their own.[ ^ 2 ]
623+ 624+ [ ^ 2 ] : It is recommended that keywords have a single resposibility. An example of
625+ this in action is the separation between ` properties ` , which verifies object
626+ property values have the right data _ if_ they exist, and ` required ` , which
627+ verifies that object properties exist. Separating these concerns allows for more
628+ reusable components.
589629
590630[ Annotation] ( #annotations ) results from subschemas are preserved in accordance
591631with {{collect}} so that applications can decide how to interpret multiple
@@ -1491,8 +1531,8 @@ operators can contact the owner of a potentially misbehaving script.
14911531
14921532## Keywords for Applying Subschemas
14931533
1494- This section defines a set of keywords that enable schema combinations and
1495- composition.
1534+ This section defines a set of applicator keywords that enable schema
1535+ combinations and composition.
14961536
14971537### Keywords for Applying Subschemas in Place {#in-place}
14981538
@@ -1752,8 +1792,8 @@ The value of this keyword MUST be a non-negative integer.
17521792This keyword modifies the behavior of ` contains ` within the same schema object,
17531793as described below in the section for that keyword.
17541794
1755- Validation MUST always succeed against this keyword . The value of this keyword
1756- is used as its annotation result.
1795+ This keyword produces no assertion result . The value of this keyword is used as
1796+ its annotation result.
17571797
17581798##### ` minContains `
17591799
@@ -1762,8 +1802,8 @@ The value of this keyword MUST be a non-negative integer.
17621802This keyword modifies the behavior of ` contains ` within the same schema object,
17631803as described below in the section for that keyword.
17641804
1765- Validation MUST always succeed against this keyword . The value of this keyword
1766- is used as its annotation result.
1805+ This keyword has no assertion behavior . The value of this keyword is used as
1806+ its annotation result.
17671807
17681808Per {{default-behaviors}}, omitted keywords MUST NOT produce annotation results.
17691809However, as described in {{contains}}, the absence of this keyword's annotation
0 commit comments