diff --git a/source/reference/array.rst b/source/reference/array.rst index d4aa6a5f..d87e5ea8 100644 --- a/source/reference/array.rst +++ b/source/reference/array.rst @@ -236,7 +236,113 @@ Unevaluated Items |draft2019-09| -Documentation Coming Soon +The ``unevaluatedItems`` keyword is useful mainly when you want to add +or disallow extra items to an array. + +``unevaluatedItems`` 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 "does not evaluate to true". + +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. + +Note that ``items`` doesn't "see inside" any instances of ``allOf``, +``anyOf``, or ``oneOf`` in the same subschema. So in this next 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] + +You can also 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" } + ], + + "$defs": { + "closed": { + "$anchor": "closed", + "$ref": "#", + "unevaluatedItems": false + } + } + } + +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" } + ], + + "$defs": { + "closed": { + "$anchor": "closed", + "$ref": "#", + "unevaluatedItems": false + } + } + } + +Thus, you would reference ``my-tuple#closed`` when you need only +two items and reference ``my-tuple#extended`` when you need three +items. .. index:: single: array; contains