Home GitHub Twitter
About Quick start Examples
The Basics
Structure Generic keywords String type Number type Integer type Boolean type Null type Object type Array type Formats Default value Conditional subschemas Multiple subschemas
Reusability
References Definitions Pointers URI Templates
Advanced features
Variables Filters Custom errors Mappers Slots Pragma Data
API
Validator Error formatter Schema loader Custom Filters Custom Formats Custom Media types Custom Content encodings Migration

Array type

Keywords for array type

Edit on GitHub

The array type is used for validating JSON indexed arrays.

{
  "type": "array"
}
Input Status
[] valid - empty array
[2, 1, "str", false, null, {}] valid
12 invalid - is integer/number
null invalid - is null
"[1, 2, 3]" invalid - is string
{"0": 1, "1": 2, "2": 3} invalid - is object

Validation keywords

The following keywords are supported by the array type, and evaluated in the presented order. All keywords are optional.

minItems

An array is valid against this keyword, if the number of items it contains is greater than, or equal to, the value of this keyword. The value of this keyword must be a non-negative integer.

{
  "type": "array",
  "minItems": 2
}

Array must have at least 2 items.

Input Status
[1, 2, 3] valid - contains more than 2 items
["a", "b"] valid - contains 2 items
["text"] invalid - contains a single item
[] invalid - contains no items

maxItems

An array is valid against this keyword, if the number of items it contains is lower than, or equal to, the value of this keyword. The value of this keyword must be a non-negative integer.

{
  "type": "array",
  "maxItems": 2
}

Array can have at most 2 items.

Input Status
[1, 2] valid - contains 2 items
["a"] valid - contains a single item
[] valid - contains no items
[1, 2, 3] invalid - contains more than 2 items

uniqueItems

An array is valid against this keyword if an item cannot be found more than once in the array. The value of this keyword must be a boolean. If set to false the keyword validation will be ignored.

Be aware of additional processing time needed when enabling uniqueItems for large JSON arrays, especially arrays of objects.

{
  "type": "array",
  "uniqueItems": true
}

Array must have unique items (for every data type).

Input Status
[1, 2, 3] valid
["a", "b", "c"] valid
[1, "1"] valid
[[1, 2], [3, 4]] valid
[1, 2, 1] invalid - duplicate 1
["a", "b", "B", "a"] invalid - duplicate a
[[1, 2], [1, 3], [1, 2]] invalid - duplicate [1, 2]
[{"a": 1, "b": 2}, {"a": 1, "c": 2}, {"a": 1, "b": 2}] invalid - duplicate {"a": 1, "b": 2}

contains

An array is valid against this keyword if at least one item is valid against the schema defined by the keyword value. The value of this keyword must be a valid json schema (object or boolean).

Please note that an empty array will never be valid against this keyword.

{
  "type": "array",
  "contains": {
    "type": "integer"
  }
}

Array must contain at least one integer.

Input Status
[1] valid
[1, 2] valid
["a", "b" -4.0] valid
[] invalid
["a", "b", "1"] invalid
[2.3, 4.5, -6.7] invalid

minContains

An array is valid against this keyword if the number of valid items verified by the contains keyword is at least the value specified by this keyword. Value of this keyword must be a positive integer.

{
  "type": "array",
  "contains": {
    "type": "integer"
  },
  "minContains": 2
}

Array must contain at least two integers.

Input Status
[5, 8, 10, 5.5] valid - 3 integers
[5, "a", 10] valid - 2 integers
[1.2, 2.5, 5] invalid - only 1 integer

maxContains

An array is valid against this keyword if the number of valid items verified by the contains keyword is at most the value specified by this keyword. Value of this keyword must be a positive integer.

{
  "type": "array",
  "contains": {
    "type": "integer"
  },
  "maxContains": 2
}

Array must contain at most two integers.

Input Status
["a", "b"] valid - no integers
[5, "a", 10] valid - 2 integers
[5, 8, 10, "a"] invalid - 3 integer

items

An array is valid against this keyword if items are valid against the corresponding schemas provided by the keyword value. The value of this keyword can be

  • a valid json schema (object or boolean), then every item must be valid against this schema
  • an array of valid json schemas, then each item must be valid against the schema defined at the same position (index). Items that don’t have a corresponding position (array contains 5 items and this keyword only has 3) will be considered valid, unless the additionalItems keyword is present - which will decide the validity.
    *Starting with draft 2020-12, this option cannot be used anymore, use prefixItems keyword instead.
{
  "type": "array",
  "items": {
    "type": "integer",
    "minimum": 0
  }
}

Array must contain only positive integers.

Input Status
[1, 2, 3] valid
[-0, 2.0] valid
[] valid
[-2, 3, 4] invalid
["a", 2] invalid 
{
  "type": "array",
  "items": [
    {"type": "integer"},
    {"type": "string"}
  ]
}

First item of the array must be an integer and the second a string. Other items can be anything.

Input Status
[1, "a"] valid
[1.0, "a", 5.6, null, true] valid
[1] valid
[] valid
["a", 1] invalid
[5.5, "a"] invalid
[5, 6] invalid

prefixItems

An array is valid against this keyword if items are valid against the corresponding schemas provided by the keyword value. The value of this keyword must be an array of valid json schemas, and each item must be valid against the schema defined at the same position (index). Items that don’t have a corresponding position (array contains 5 items and this keyword only has 3) will be considered valid, unless the items keyword is present - which will decide the validity.

{
  "type": "array",
  "items": [
    {"type": "integer"},
    {"type": "string"}
  ]
}

First item of the array must be an integer and the second a string. Other items can be anything.

Input Status
[1, "a"] valid
[1.0, "a", 5.6, null, true] valid
[1] valid
[] valid
["a", 1] invalid
[5.5, "a"] invalid
[5, 6] invalid

additionalItems

An array is valid against this keyword if all unchecked items are valid against the schema defined by the keyword value. An item is considered unchecked if items keyword or prefixItems keyword (starting with draft 2020-12) contains an array of schemas and doesn’t have a corresponding position (index). The value of the keyword must be a valid json schema (object, boolean).

This keyword is not officially defined in draft-2020-12, but we kept it for backward compatibility reasons.
In draft-2020-12 this keyword was replaced by the items keyword, while the array version of the former items keyword was replaced by the prefixItems keyword.
You can disable it for draft-2020-12 by setting the keepAdditionalItemsKeyword option to false.

{
  "type": "array",
  "items": [
    {"type": "integer"},
    {"type": "string"}
  ],
  "additionalItems": {
    "type": "boolean"
  }
}

First item of the array must be an integer and the second a string. Other items can only be booleans.

Input Status
[1, "a", true, false, true, true] valid
[1, "a"] valid
[1] valid
[] valid
[1, "a", 2] invalid
[1, "a", true, 2, false] invalid
[1, true, false] invalid

unevaluatedItems

An array is valid against this keyword if every unevaluated item is valid against the schema defined by the value of this keyword.

Unevaluated items are the items that were not evaluated anywhere in the current schema. This keyword can see through adjacent keywords, such as allOf.

This keyword is hard to follow when you are dealing with complex schemas. Also, it slows down the validation process because short-circuits must be disabled for this keyword to work correctly. We do not recommend using it, unless you fully understand its behavior!

{
  "type": "array",
  "prefixItems": [
    { "type": "string" }
  ],
  "allOf": [
    {
      "prefixItems": [
        true,
        { "type": "number" }
      ]
    }
  ],
  "unevaluatedItems": false
}

Schema doesn’t allow unevaluated items.

Input Status
["foo", 42] valid - all evaluated
["foo", 42, true] invalid - true is unevaluated

You can disable unevaluatedItems keyword by setting the allowUnevaluated option to false.

Keywords for object type

Object type

Default formats

Formats
Copyright © Zindex Software. All rights reserved
On this page