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 2019-09
Changed In None
Introduced In 2019-09
Vocabulary Applicator
Specification https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.section.9.3.1.3
Metaschema https://json-schema.org/draft/2019-09/meta/applicator
Official Tests draft2019-09/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 additionalItems keyword that considers related keywords even when they are not direct siblings of this keyword. More specifically, this keyword is affected by occurrences of items, additionalItems, 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/2019-09/schema",
  "if": { "maxItems": 3 },
  "then": { "items": [ { "type": "string" } ] },
  "else": { "items": { "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/items", "instance": "", "value": 0 }
{ "keyword": "/unevaluatedItems", "instance": "", "value": true }
Valid An array value that contains only boolean items is valid Instance 
[ true, false, true ]
Annotations 
{ "keyword": "/else/items", "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 is invalid Instance 
[ true, 2, false ]
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/2019-09/schema",
  "$ref": "#/$defs/string-first-item",
  "unevaluatedItems": false,
  "$defs": {
    "string-first-item": {
      "items": [ { "type": "string" } ]
    }
  }
}
Valid An array value that only contains a string item is valid Instance 
[ "foo" ]
Annotations 
{ "keyword": "/$defs/string-first-item/items", "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/2019-09/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/2019-09/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"