From c0b8ac6d4ea288d71ccd11bd7dcd646f7327b1dc Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 11 Jun 2018 21:50:54 -0700 Subject: [PATCH 1/2] Initial description of annotation collection This covers the basics of annotation collection, and its interaction with assertions and applicators. It does not get into the exact output structure for annotation results, which is intentional. The goal is to establish the process, and then nail down the format once the process is solid. --- jsonschema-core.xml | 90 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 508266db..d23de1b7 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1140,6 +1140,94 @@ +
+ + + The exact structure and format of the information collected is TBD, + but will be defined before the next draft. Some details of this + section may change as a result, but the overall process is expected + to remain the same. See GitHub issue #396 to track progress. + + + + Annotations are collected by keywords that explicitly define + annotation-collecting behavior. Note that boolean schemas cannot + produce annotations as they do not make use of keywords. + + + A collected annotation MUST include the following information: + + + The name of the annotation, which MUST be identical to the keyword + that defines that annotation. + + + The instance location to which it is attached, as a JSON Pointer + + + The schema location of the attaching keyword, as a list of URIs + constructed as described below + + + The attached value(s) + + + + + If multiple schema locations attach values to the same instance location, + and the annotation defines a process for combining such values, then the + combined value MUST also be associated with the instance location. + + + Applications MAY make decisions on which of multiple annotation values + to use based on the schema location that contributed the value. + This is intended to allow flexible usage. Collecting the schema location + facilites such usage. + + + For example, one application may consider a "description" annotation that is + in the same schema object as a "$ref" to override any "description" in the + reference's target schema. A different application may prefer to concatenate + all "description" annotations based on whatever ordering it defines. + +
+ + If any keyword in a schema object produces a false assertion + result, then all annotations from all keywords in that schema + object, and any of its subschemas or referenced schemas, MUST + be discarded. + + + This may be due to an assertion keyword directly producing + a false result, or an applicator keyword producing a false + assertion result as the aggregate assertion result of + its subschema(s). + +
+
+ + In addition to possibly defining annotation results of their own, + applicator keywords aggregate the annotations collected in their + subschema(s) or referenced schema(s). The rules for aggregating + annotation values are defined by each annotation keyword, and are + not directly affected by the logic used for combining assertion + results. + + + If, in the process of aggregating subscheama results, an applicator + keyword modifies a subschema's assertion result to be false, all + annotation keywords from that subschema MUST be discarded. + + + Note that this means that an applicator such as "not" + will never produce annotation results: Either the subschema failed an + assertion and discarded its annotations before "not" processes them, or if + the subschema passed all assertions, "not" will invert that to a failure, + and then discard the annotations before producing its own result. + +
+
+
This section defines a vocabulary of applicator keywords that @@ -1213,7 +1301,7 @@
-
+
This keyword's value MUST be a valid JSON Schema. From 9aaa8b5df8c2bb51212537d91d707d6cd698a1d7 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 30 Jun 2018 13:48:35 -0700 Subject: [PATCH 2/2] Incorporate feedback on annotation collection * Simplify wording around annotation keywords and names * Remove potentially confusing details about the collection process, particularly regarding applicators such as "not" * Add an example to clarify why the handling of multiple annotation values is deferred to applications, and show how applications might make use of this flexibility. --- jsonschema-core.xml | 175 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 136 insertions(+), 39 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index d23de1b7..74954cd8 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1158,15 +1158,18 @@ A collected annotation MUST include the following information: - The name of the annotation, which MUST be identical to the keyword - that defines that annotation. + The name of the keyword that produces the annotation The instance location to which it is attached, as a JSON Pointer - The schema location of the attaching keyword, as a list of URIs - constructed as described below + The absolute schema location of the attaching keyword, as a URI + + + The schema location path, indicating how reference keywords + such as "$ref" were followed to reach the absolute schema location + The exact format of this path is TBD, again see issue #396 The attached value(s) @@ -1174,34 +1177,140 @@ - If multiple schema locations attach values to the same instance location, - and the annotation defines a process for combining such values, then the - combined value MUST also be associated with the instance location. - - - Applications MAY make decisions on which of multiple annotation values - to use based on the schema location that contributed the value. - This is intended to allow flexible usage. Collecting the schema location - facilites such usage. - - - For example, one application may consider a "description" annotation that is - in the same schema object as a "$ref" to override any "description" in the - reference's target schema. A different application may prefer to concatenate - all "description" annotations based on whatever ordering it defines. + If the same keyword attaches values from multiple schema locations + to the same instance location, and the annotation defines a process + for combining such values, then the combined value MUST also be associated + with the instance location. +
+ + Applications MAY make decisions on which of multiple annotation values + to use based on the schema location that contributed the value. + This is intended to allow flexible usage. Collecting the schema location + facilitates such usage. + + + For example, consider this schema, which uses annotations and assertions from + the Validation specification: + +
+ + Note that some lines are wrapped for clarity. + + + + +
+ + In this example, both Feature A and Feature B make use of the re-usable + "enabledToggle" schema. That schema uses the "title", "description", + and "default" annotations, none of which define special behavior for + handling multiple values. Therefore the application has to decide how + to handle the additional "default" value for Feature A, and the additional + "description" value for Feature B. + + + The application programmer and the schema author need to agree on the + usage. For this example, let's assume that they agree that the most + specific "default" value will be used, and any additional, more generic + "default" values will be silently ignored. Let's also assume that they + agree that all "description" text is to be used, starting with the most + generic, and ending with the most specific. This requires the schema + author to write descriptions that work when combined in this way. + + + The application can use the schema location path to determine which + values are which. The values in the feature's immediate "enabled" + property schema are more specific, while the values under the re-usable + schema that is referred to with "$ref" are more generic. The schema + location path will show whether each value was found by crossing a + "$ref" or not. + + + Feature A will therefore use a default value of true, while Feature B + will use the generic default value of null. Feature A will only + have the generic description from the "enabledToggle" schema, while + Feature B will use that description, and also append its locally + defined description that explains how to interpret a null value. + + + Note that there are other reasonable approaches that a different application + might take. For example, an application may consider the presence of + two different values for "default" to be an error, regardless of their + schema locations. + +
- If any keyword in a schema object produces a false assertion - result, then all annotations from all keywords in that schema - object, and any of its subschemas or referenced schemas, MUST - be discarded. + Schema objects that produce a false assertion result MUST NOT + produce any annotation results, whether from their own keywords + or from keywords in subschemas. - This may be due to an assertion keyword directly producing - a false result, or an applicator keyword producing a false - assertion result as the aggregate assertion result of - its subschema(s). + Note that the overall schema results may still include annotations + collected from other schema locations. Given this schema: + +
+ + + +
+ + And the instance "This is a string", the + title annotation "Integer Value" is discarded because the type assertion + in that schema object fails. The title annotation "String Value" + is kept, as the instance passes the string type assertions.
@@ -1213,18 +1322,6 @@ not directly affected by the logic used for combining assertion results. - - If, in the process of aggregating subscheama results, an applicator - keyword modifies a subschema's assertion result to be false, all - annotation keywords from that subschema MUST be discarded. - - - Note that this means that an applicator such as "not" - will never produce annotation results: Either the subschema failed an - assertion and discarded its annotations before "not" processes them, or if - the subschema passed all assertions, "not" will invert that to a failure, - and then discard the annotations before producing its own result. -