Emphasize and clarify annotations

This does not change the intended behavior, but generalizes some
points presented as exceptions (e.g. why annotations under "not"
are never used), and calls annotations out as a first-class use
case in the core specification.

Author: handrews

jsonschema-core.xml

@@ -137,6 +137,19 @@
                 </t>
             </section>
 
+            <section title="Annotation">
+                <t>
+                    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.
+                </t>
+                <t>
+                    Detailed annotation behavior, along with a small set of basic annotation
+                    keywords are defined in
+                    <xref target="json-schema-validation">the validation specification</xref>.
+                </t>
+            </section>
+
             <section title="Hypermedia and Linking">
                 <t>
                     JSON Hyper-Schema describes the hypertext structure of a JSON document.
@@ -1160,6 +1173,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
                     <t hangText="draft-handrews-json-schema-01">
                         <list style="symbols">
                             <t>This draft is purely a clarification with no functional changes</t>
+                            <t>Emphasized annotations as a primary usage of JSON Schema</t>
                             <t>Clarified $id by use cases</t>
                             <t>Exhaustive schema identification examples</t>
                             <t>Replaced "external referencing" with how and when an implementation might know of a schema from another doucment</t>

jsonschema-validation.xml

@@ -246,12 +246,22 @@
                     Additional vocabularies SHOULD make use of this mechanism for applying
                     their own annotations to instances.
                 </t>
-                <section title="Negated Schemas">
+                <section title="Annotations and Validation Outcomes">
                     <t>
-                        Annotations in a subschema contained within a "not", at any depth,
-                        including any number of intervening additional "not" subschemas, MUST be
-                        ignored.  Similarly, annotations within a failing branch of a "oneOf",
-                        "anyOf", "then", or "else" MUST be ignored.
+                        Annotations are collected whenever an instance is valid against
+                        a schema object, and all of that schema object's parent schemas.
+                    </t>
+                    <t>
+                        In particular, annotations in a subschema contained within a "not",
+                        at any depth, including any number of intervening additional "not"
+                        subschemas, MUST be ignored.  If the instance was valid against the
+                        "not" subschema, then by definition it is not valid against the schema
+                        that contains the "not", so the "not" subschema's annotations are not used.
+                    </t>
+                    <t>
+                        Similarly, annotations within a failing branch of a "oneOf", "anyOf",
+                        "then", or "else" MUST be ignored even when the instance successfully
+                        validates against the complete schema document.
                     </t>
                 </section>
                 <section title="Annotations and Short-Circuit Validation">
@@ -1494,8 +1504,9 @@
                     <t hangText="draft-handrews-json-schema-validation-01">
                         <list style="symbols">
                             <t>This draft is purely a clarification with no functional changes</t>
-                            <t>Restored ommitted "if present" clause for "else" under "if"</t>
-                            <t>Clarified that when "if" is absent, the results of "then" and "else" are ignored</t>
+                            <t>Provided the general principle behind ignoring annotations under "not" and similar cases</t>
+                            <t>Clarified "if"/"then"/"else" validation interactions</t>
+                            <t>Clarified "if"/"then"/"else" behavior for annotation</t>
                             <t>Minor formatting and cross-referencing improvements</t>
                         </list>
                     </t>