From efe6664f9cdf9a1105eda798bebab9bbac935d78 Mon Sep 17 00:00:00 2001
From: Henry Andrews <andrews_henry@yahoo.com>
Date: Sat, 5 Sep 2020 21:07:52 -0700
Subject: [PATCH] Remove special case handling of annotation values

The approach of annotation keywords specifying combination rules
is not really compatible with the output format approach.  It is
also a source of uncertainty in how to use and specify annotations.

This removes the concept.  Note that "readOnly", "writeOnly", and
"deprecated" still advise applications on how to handle multiple
values.  However, the wording is purely in terms of application
handling and not in terms of aggregating the values, so no change
to the validation spec is necessary.
---
 jsonschema-core.xml | 25 ++++++++-----------------
 1 file changed, 8 insertions(+), 17 deletions(-)

diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 6288e746..3a10d124 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -770,7 +770,9 @@
                 </t>
                 <t>
                     <xref target="annotations">Annotation</xref> results are
-                    combined according to the rules specified by each annotation keyword.
+                    preserved along with the instance location and the location of
+                    the schema keyword, so that applications can decide how to
+                    interpret multiple values.
                 </t>
                 <section title="Referenced and Referencing Schemas" anchor="referenced">
                     <t>
@@ -865,8 +867,9 @@
                 <t>
                     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.
+                    location, applications may need to decide how to handle differing
+                    annotation values being attached to the same instance location by
+                    the same schema keyword in different schema objects.
                 </t>
                 <t>
                     Unlike assertion results, annotation data can take a wide variety of forms,
@@ -919,14 +922,6 @@
                             </t>
                         </list>
                     </t>
-                    <t>
-                        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.  The <xref target="output">output formats</xref>
-                        described in this specification that include annotation information
-                        meet this requirement.
-                    </t>
                     <section title="Distinguishing Among Multiple Values">
                         <t>
                             Applications MAY make decisions on which of multiple annotation values
@@ -986,8 +981,7 @@
                         <t>
                             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
+                            and "default" annotations.  Therefore the application has to decide how
                             to handle the additional "default" value for Feature A, and the additional
                             "description" value for Feature B.
                         </t>
@@ -1061,10 +1055,7 @@
                         <t>
                             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.
+                            subschema(s) or referenced schema(s).
                         </t>
                     </section>
                 </section>