diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 508266db..74954cd8 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -1140,6 +1140,191 @@
+
+
+
+ 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 keyword that produces the annotation
+
+
+ The instance location to which it is attached, as a JSON Pointer
+
+
+ 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)
+
+
+
+
+ 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.
+
+
+
+
+ Schema objects that produce a false assertion result MUST NOT
+ produce any annotation results, whether from their own keywords
+ or from keywords in subschemas.
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
This section defines a vocabulary of applicator keywords that
@@ -1213,7 +1398,7 @@
-
+
This keyword's value MUST be a valid JSON Schema.