Merge pull request #1042 from Relequestual/issue/942-clarify-contains

Clarify contains when applying to an empty array

Author: Relequestual

jsonschema-core.xml

@@ -2360,16 +2360,23 @@
                         </t>
                         <t>
                             An array instance is valid against "contains" if at least one of
-                            its elements is valid against the given schema.  Note that when
-                            collecting annotations, the subschema MUST be applied to every
-                            array element even after the first match has been found.  This
-                            is to ensure that all possible annotations are collected.
+                            its elements is valid against the given schema. The subschema MUST be
+                            applied to every array element even after the first match has
+                            been found, in order to collect annotations for use by other keywords.
+                            This is to ensure that all possible annotations are collected.
+                        </t>
+                        <t>
+                            Logically, the validation result of applying the value subschema to each
+                            item in the array MUST be ORed with "false", resulting in an overall
+                            validation result.
                         </t>
                         <t>
                             This keyword produces an annotation value which is an array of
                             the indexes to which this keyword validates successfully when applying
-                            its subschema, in ascending order. The value MAY be a boolean true if the
+                            its subschema, in ascending order. The value MAY be a boolean "true" if the
                             subschema validated successfully when applied to every index of the instance.
+                            If the instance array this keywords subschema is applicable to is empty,
+                            the annotation value MUST NOT be missing.
                         </t>
                     </section>
                 </section>

jsonschema-validation.xml

@@ -408,37 +408,41 @@
                     <t>
                         The value of this keyword MUST be a non-negative integer.
                     </t>
-                    <t>
-                        An array instance is valid against "maxContains" if the number of
-                        elements that are valid against the schema for
-                        <xref target="json-schema">"contains"</xref> is
-                        less than, or equal to, the value of this keyword.
-                    </t>
                     <t>
                         If "contains" is not present within the same schema object,
                         then this keyword has no effect.
                     </t>
+                    <t>
+                        An array instance is valid against "maxContains" if its
+                        value is less than or equal to, the array length of the annotation
+                        result from an adjacent
+                        <xref target="json-schema">"contains"</xref> keyword where the
+                        annotation is an array, or the length of the instance array
+                        where the annotation is "true".
+                    </t>
                 </section>
 
                 <section title="minContains">
                     <t>
                         The value of this keyword MUST be a non-negative integer.
                     </t>
                     <t>
-                        An array instance is valid against "minContains" if the number of
-                        elements that are valid against the schema for
-                        <xref target="json-schema">"contains"</xref> is
-                        greater than, or equal to, the value of this keyword.
+                        If "contains" is not present within the same schema object,
+                        then this keyword has no effect.
+                    </t>
+                    <t>
+                        An array instance is valid against "minContains" if its
+                        value is greater than or equal to, the array length of the annotation
+                        result from an adjacent
+                        <xref target="json-schema">"contains"</xref> keyword where the
+                        annotation is an array, or the length of the instance array
+                        where the annotation is "true".
                     </t>
                     <t>
                         A value of 0 is allowed, but is only useful for setting a range
                         of occurrences from 0 to the value of "maxContains".  A value of
                         0 with no "maxContains" causes "contains" to always pass validation.
                     </t>
-                    <t>
-                        If "contains" is not present within the same schema object,
-                        then this keyword has no effect.
-                    </t>
                     <t>
                         Omitting this keyword has the same behavior as a value of 1.
                     </t>