unevaluatedItems : Schema

unevaluatedItems

Schema

Validates array elements that did not successfully validate against other standard array applicators.

Value This keyword must be set to a valid JSON Schema Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
Kind Applicator Annotation
Applies To Array
Base Dialect 2020-12
Changed In None
Introduced In 2019-09
Vocabulary Unevaluated
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-11.2
Metaschema https://json-schema.org/draft/2020-12/meta/unevaluated
Official Tests draft2020-12/unevaluatedItems.json
Default {}
Annotation Boolean A boolean true if it applied to any item of the instance Hint: Use the jsonschema validate command to collect annotations from the command-line
Affected By
Affects None
Also See

The unevaluatedItems keyword is a generalisation of the items keyword that considers related keywords even when they are not direct siblings of this keyword. More specifically, this keyword is affected by occurences of prefixItems, items, contains, and unevaluatedItems itself, as long as the evaluate path that led to unevaluatedItems is a prefix of the evaluate path of the others.

Given its evaluation-dependent nature, this keyword is evaluated after every other keyword from every other vocabulary.

Remember that JSON Schema is a constraint-driven language. Therefore, non-array instances successfully validate against this keyword. If needed, make use of the type keyword to constraint the accepted type accordingly.

Examples

A schema that conditionally constrains array instances to contain certain items, with number additional items in both cases Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "if": { "maxItems": 3 },
  "then": { "prefixItems": [ { "type": "string" } ] },
  "else": { "contains": { "type": "boolean" } },
  "unevaluatedItems": { "type": "number" }
}
Valid An array value that contains a string property and other number items is valid Instance 
[ "foo", 1, 2 ]
Annotations 
{ "keyword": "/then/prefixItems", "instance": "", "value": 0 }
{ "keyword": "/unevaluatedItems", "instance": "", "value": true }
Valid An array value that contains multiple boolean and number items is valid Instance 
[ true, 1, false, 2, true, 3 ]
Annotations 
{ "keyword": "/else/contains", "instance": "", "value": [ 0, 2, 4 ] }
{ "keyword": "/unevaluatedItems", "instance": "", "value": true }
Invalid An array value that contains a string property and other non-number items is invalid Instance 
[ "foo", "bar", "baz" ]
Invalid An array value that contains multiple boolean and number items, and string additional items is invalid Instance 
[ true, 2, "foo", "bar" ]
Valid An empty array value is valid Instance 
{}
Valid A non-array value is valid Instance 
"Hello World"
A schema that constraints array instances to only allow a single string item using a helper Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$ref": "#/$defs/string-first-item",
  "unevaluatedItems": false,
  "$defs": {
    "string-first-item": {
      "prefixItems": [ { "type": "string" } ]
    }
  }
}
Valid An array value that only contains a string item is valid Instance 
[ "foo" ]
Annotations 
{ "keyword": "/$defs/string-first-item/prefixItems", "instance": "", "value": 0 }
Invalid An array value that contains a string item and other items is invalid Instance 
[ "foo", 2, 3 ]
Valid An empty array value is valid Instance 
{}
Valid A non-array value is valid Instance 
"Hello World"
A schema that constraints array instances to not define any items, as both array keywords are cousins Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "allOf": [
    { "items": true },
    { "unevaluatedItems": false }
  ]
}
Invalid An array value that contains any item is invalid as the schema prohibits unevaluated items Instance 
[ 1, 2, 3 ]
Valid An empty array value is valid Instance 
[]
Valid A non-array value is valid Instance 
"Hello World"
A schema that constraints array instances to define arbitrary items Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "allOf": [ { "unevaluatedItems": true } ],
  "unevaluatedItems": false
}
Valid An array value that contains any item is valid as the nested applicator takes precedence Instance 
[ 1, 2, 3 ]
Annotations 
{ "keyword": "/allOf/0/unevaluatedItems", "instance": "", "value": true }
Valid An empty array value is valid Instance 
{}
Valid A non-array value is valid Instance 
"Hello World"