add rough docs for unevaluatedItems

source/reference/array.rst

@@ -236,7 +236,113 @@ Unevaluated Items
 
 |draft2019-09|
 
-Documentation Coming Soon
+The ``unevaluatedItems`` keyword applies to any values not evaluated
+by an ``items``, ``prefixItems``, or ``contains`` keyword. Just as
+``unevaluatedProperties`` affects only **properties** in an object,
+``unevaluatedItems`` affects only **items** in an array.
+
+.. note::
+    Watch out! The word "unevaluated" *does not mean* "not evaluated by
+    ``items``, ``prefixItems``, or ``contains``." "Unevaluated" means
+    "not successfully evaluated", or "doesn't evaluate to true".
+
+``items`` doesn't "see inside" any instances of ``allOf``, ``anyOf``,
+or ``oneOf`` in the same subschema. In this first example, ``items``
+ignores ``allOf`` and thus fails to validate.
+
+.. schema_example::
+
+    {
+      "allOf": [{ "prefixItems": [{ "type": "boolean" }, { "type": "string" }] }],
+      "items": { "const": 2 }
+    }
+    --X
+    [true, "a", 2]
+
+But if you replace ``items`` with ``unevaluatedItems``, then the same
+array validates.
+
+.. schema_example::
+
+    {
+      "allOf": [{ "prefixItems": [{ "type": "boolean" }, { "type": "string" }] }],
+      "unevaluatedItems": { "const": 2 }
+    }
+    --
+    [true, "a", 2]
+
+Like with ``items``, if you set ``unevaluatedItems`` to ``false``, you
+can disallow extra items in the array.
+
+.. schema_example::
+
+    {
+      "prefixItems": [
+        { "type": "string" }, { "type": "number" }
+      ],
+      "unevaluatedItems": false
+    }
+    --
+    ["foo", 42]
+    // All the values are evaluated. The schema passes validation.
+    --X
+    ["foo", 42, null]
+    // The schema fails validation because ``"unevaluatedItems": false"``
+    // specifies no extra values should exist.
+
+``unevaluatedItems`` is used mainly when extending a tuple. So with
+this in mind, you can make a "half-closed" schema: something useful
+when you want to keep the first two arguments, but also add more in
+certain situations. ("Closed" to two arguments in some places, "open"
+to more arguments when you need it to be.)
+
+.. schema_example::
+
+    {
+      "$id": "https://example.com/my-tuple",
+
+      "type": "array",
+      "prefixItems": [
+        { "type": "boolean" },
+        { "type": "string" }
+      ],
+      "unevaluatedItems": false,
+
+      "$defs": {
+        "closed": {
+          "$anchor": "closed",
+          "$ref": "#"
+        }
+      }
+    }
+
+Here the schema is "closed" to two array items. You can then later
+use ``$ref`` and add another item like this:
+
+.. schema_example::
+
+    {
+      "$id": "https://example.com/my-extended-tuple",
+
+      "$ref": "https://example.com/my-tuple",
+      "prefixItems": [
+        { "type": "boolean" },
+        { "type": "string" },
+        { "type": "number" }
+      ],
+      "unevaluatedItems": false,
+
+        "$defs": {
+          "extended": {
+            "$anchor": "extended",
+            "$ref": "#"
+        }
+      }
+    }
+
+Thus, you would reference ``my-tuple#closed`` when you need only
+two array items and reference ``my-tuple#extended`` when you need
+three items.
 
 .. index::
    single: array; contains