From 3546fa0f84f50f37ab16247f2ba785ddeb6e9f3e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 25 May 2018 11:46:10 -0700 Subject: [PATCH 1/5] Create an Applicators section Move the general description of applicators from the applicator vocabulary to a section alongside the Assertion and Annotation sections. Rework the text a bit, and also clarify an aspect of annotation collection related to applicators. --- jsonschema-core.xml | 50 +++++++++++++++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 557f2747..95f98e5f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -123,7 +123,32 @@ data in several ways. -
+
+ + Evaluation of an instance against a + schema document begins by applying + the root schema to the complete instance document. + From there, keywords known as applicators are used to determine which + additional subschemas are applied. Subschema may be applied in-place + to the current location, or to a child location. The subschemas may be all + or part of the keyword's value, or the keyword's value may identify one + or more schemas in a way defined by the keyword. + + + Applicator keywords also define how subschema booolean + assertion + 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 results are + combined according to the rules specified by each annotation keyword. + +
+ +
JSON Schema can be used to assert constraints on a JSON document, which either passes or fails the assertions. This approach can be used to validate @@ -167,7 +192,12 @@ Since many subschemas can be applied to any single location, annotation keywords need to specify any unusual handling of multiple applicable occurrences of the keyword with different values. - The default behavior is simply to collect all values. + + + The default behavior is simply to collect all values in a list in + indeterminate order. Given the extensibility of keywords, including + applicators, it is not possible to define a universally predictable + order of processing. Unlike assertion results, annotation data can take a wide variety of forms, @@ -363,7 +393,7 @@
-
+
A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. @@ -439,7 +469,7 @@ and implementations.
-
+
The root schema is the schema that comprises the entire JSON document in question. @@ -973,17 +1003,7 @@
- Evaluation of an instance against a schema begins by applying the root schema - to the complete instance document. From there, various keywords are used - to determine which additional subschemas are applied to either the current - location, or a child location. These keywords also define how subschema - assertion results are modified and/or combined. Annotation results are - combined according to the rules specified by each annotation keyword. - - - Keyword that apply subschemas are called applicators, and do not assert - conditions on their own. Rather, they control how assertions are applied - and evaluated. This section defines a set of applicator keywords that + This section defines a vocabulary of applicator keywords that are RECOMMENDED for use as the basis of other vocabularies.
From 9740818954abf65405eddfec211d25d5af2917b2 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 25 May 2018 17:33:13 -0700 Subject: [PATCH 2/5] Make a Keyword Behavior section This is purely a reformatting plus the new section tags, no text has been changed. Group the Annotation, Assertion, and Application sections. This new section will get an intro paragraph in the next commit. Arguably, this has overgrown the "Overview" section, but since the "Vocabulary" part of the overview is also about to be expanded, let's wait until then to figure out how to refactor it. --- jsonschema-core.xml | 162 ++++++++++++++++++++++---------------------- 1 file changed, 82 insertions(+), 80 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 95f98e5f..0c9823fd 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -123,93 +123,95 @@ data in several ways. -
- - Evaluation of an instance against a - schema document begins by applying - the root schema to the complete instance document. - From there, keywords known as applicators are used to determine which - additional subschemas are applied. Subschema may be applied in-place - to the current location, or to a child location. The subschemas may be all - or part of the keyword's value, or the keyword's value may identify one - or more schemas in a way defined by the keyword. - - - Applicator keywords also define how subschema booolean - assertion - 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 results are - combined according to the rules specified by each annotation keyword. - -
+
+
+ + Evaluation of an instance against a + schema document begins by applying + the root schema to the complete instance + document. From there, keywords known as applicators are used to determine + which additional subschemas are applied. Subschema may be applied in-place + to the current location, or to a child location. The subschemas may be all + or part of the keyword's value, or the keyword's value may identify one + or more schemas in a way defined by the keyword. + + + Applicator keywords also define how subschema booolean + assertion + 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 results are + combined according to the rules specified by each annotation keyword. + +
-
- - JSON Schema can be used to assert constraints on a JSON document, which - either passes or fails the assertions. This approach can be used to validate - conformance with the constraints, or document what is needed to satisfy them. - - - JSON Schema implementations produce a single boolean result when evaluating - an instance against schema assertions. - - - An instance can only fail an assertion that is present in the schema. - In some cases, this no-op behavior is identical to a keyword that exists with - certain values, and keyword defintions SHOULD note such values where known. - These default behaviors MUST NOT result in assertion failures. - -
+
+ + JSON Schema can be used to assert constraints on a JSON document, which + either passes or fails the assertions. This approach can be used to validate + conformance with the constraints, or document what is needed to satisfy them. + - Most assertions only constrain values within a certain - primitive type. When the type of the instance is not of the type - targeted by the keyword, the instance is considered to conform - to the assertion. + JSON Schema implementations produce a single boolean result when evaluating + an instance against schema assertions. - For example, the "maxLength" keyword from the companion validation - vocabulary will only restrict certain strings - (that are too long) from being valid. If the instance is a number, - boolean, null, array, or object, then it is valid against this assertion. + An instance can only fail an assertion that is present in the schema. + In some cases, this no-op behavior is identical to a keyword that exists with + certain values, and keyword defintions SHOULD note such values where known. + These default behaviors MUST NOT result in assertion failures. +
+ + Most assertions only constrain values within a certain + primitive type. When the type of the instance is not of the type + targeted by the keyword, the instance is considered to conform + to the assertion. + + + For example, the "maxLength" keyword from the companion validation + vocabulary will only restrict certain strings + (that are too long) from being valid. If the instance is a number, + boolean, null, array, or object, then it is valid against this assertion. + +
-
-
- - JSON Schema can annotate an instance with information, whenever the instance - validates against the schema object containing the annotation, and all of its - parent schema objects. The information can be a simple value, or can be - calculated based on the instance contents. - - - Annotations are attached to specific locations in an instance. - Since many subschemas can be applied to any single - location, annotation keywords need to specify any unusual handling of - multiple applicable occurrences of the keyword with different values. - - - The default behavior is simply to collect all values in a list in - indeterminate order. Given the extensibility of keywords, including - applicators, it is not possible to define a universally predictable - order of processing. - - - Unlike assertion results, annotation data can take a wide variety of forms, - which are provided to applications to use as they see fit. JSON Schema - implementations are not expected to make use of the collected information - on behalf of applications. - - - While "short-circuit" evaluation is possible for assertions, collecting - annotations requires examining all schemas that apply to an instance - location, even if they cannot change the overall assertion result. - +
+ + JSON Schema can annotate an instance with information, whenever the instance + validates against the schema object containing the annotation, and all of its + parent schema objects. The information can be a simple value, or can be + calculated based on the instance contents. + + + Annotations are attached to specific locations in an instance. + Since many subschemas can be applied to any single + location, annotation keywords need to specify any unusual handling of + multiple applicable occurrences of the keyword with different values. + + + The default behavior is simply to collect all values in a list in + indeterminate order. Given the extensibility of keywords, including + applicators, it is not possible to define a universally predictable + order of processing. + + + Unlike assertion results, annotation data can take a wide variety of forms, + which are provided to applications to use as they see fit. JSON Schema + implementations are not expected to make use of the collected information + on behalf of applications. + + + While "short-circuit" evaluation is possible for assertions, collecting + annotations requires examining all schemas that apply to an instance + location, even if they cannot change the overall assertion result. + +
From 18844c1fe347917e95f43c5587de15147fd6fd37 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 25 May 2018 19:00:36 -0700 Subject: [PATCH 3/5] Add an intro for Keyword Behaviors This attempts to explain the general framework for keywords and provide guidance on creating new keywords with respect to that framework. --- jsonschema-core.xml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 0c9823fd..c4fb9441 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -124,6 +124,20 @@
+ + JSON Schema keywords fall into several general behavior categories. + Assertions validate that an instance satisfies constraints, annotations + attach information that applications may use in any way they see fit, + and applicators allow for building more complex schemas than a single + schema object would allow. + + + Extension keywords SHOULD stay within these categories, 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. +
Evaluation of an instance against a From 719629d3bec7b0149e3f47327c96578603ec613e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 25 May 2018 19:01:21 -0700 Subject: [PATCH 4/5] Fix some typos --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c4fb9441..46458905 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -150,7 +150,7 @@ or more schemas in a way defined by the keyword. - Applicator keywords also define how subschema booolean + Applicator keywords also define how subschema boolean assertion results are modified and/or combined to produce the boolean result of the applicator. Applicators may apply any boolean logic operation @@ -176,7 +176,7 @@ An instance can only fail an assertion that is present in the schema. In some cases, this no-op behavior is identical to a keyword that exists with - certain values, and keyword defintions SHOULD note such values where known. + certain values, and keyword definitions SHOULD note such values where known. These default behaviors MUST NOT result in assertion failures.
From e80b135c18498edb4e000a6702d434f53d80a03d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 11 Jun 2018 22:04:53 -0700 Subject: [PATCH 5/5] Explain evaluation, minor wording improvements --- jsonschema-core.xml | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 46458905..937e5f7f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -126,10 +126,24 @@
JSON Schema keywords fall into several general behavior categories. - Assertions validate that an instance satisfies constraints, annotations - attach information that applications may use in any way they see fit, - and applicators allow for building more complex schemas than a single - schema object would allow. + Assertions validate that an instance satisfies constraints. 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. + + + 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 therefore no subschemas) is reached. The appropriate + location in the instance is evaluated against the assertion and + annotation keywords in the schema object, and their results are gathered + into the parent schema according to the rules of the applicator. + + + Evaluation of a parent schema object can complete once all of its + subschemas have been evaluated, although in some circumstance evaluation + may be short-circuited due to assertion results. Extension keywords SHOULD stay within these categories, keeping in mind @@ -140,7 +154,8 @@
- Evaluation of an instance against a + Applicators allow for building more complex schemas than can be accomplished + with a single schema object. Evaluation of an instance against a schema document begins by applying the root schema to the complete instance document. From there, keywords known as applicators are used to determine