Arrays are used for ordered elements. In JSON, each element in an array may be of a different type.
In Python, "array" is analogous to a
depending on usage. However, the
json module in the Python
standard library will always use Python lists to represent JSON
There are two ways in which arrays are generally used in JSON:
- List validation: a sequence of arbitrary length where each item matches the same schema.
- Tuple validation: a sequence of fixed length where each item may
have a different schema. In this usage, the index (or location) of
each item is meaningful as to how the value is interpreted. (This
usage is often given a whole separate type in some programming
languages, such as Python's
List validation is useful for arrays of arbitrary length where each item
matches the same schema. For this kind of array, set the
to a single schema that will be used to validate all of the items in the
In the following example, we define that each item in an array is a number:
A single "non-number" causes the whole array to be invalid:
The empty array is always valid:
Tuple validation is useful when the array is a collection of items where each has a different schema and the ordinal index of each item is meaningful.
For example, you may represent a street address such as
1600 Pennsylvania Avenue NW as a 4-tuple of the form:
[number, street_name, street_type, direction]
Each of these fields will have a different schema:
number: The address number. Must be a number.
street_name: The name of the street. Must be a string.
street_type: The type of street. Should be a string from a fixed set of values.
direction: The city quadrant of the address. Should be a string from a different set of values.
To do this, we use the
prefixItems is an array,
where each item is a schema that corresponds to each index of the
document's array. That is, an array where the first element validates
the first element of the input array, the second element validates the
second element of the input array, etc.
itemswas an array of schemas instead of a single schema, it behaved the way
Here's the example schema:
"Drive" is not one of the acceptable street types:
This address is missing a street number:
It's okay to not provide all of the items:
And, by default, it's also okay to add additional items to end:
items keyword can be used to control whether it's valid to have
additional items in a tuple beyond what is defined in
value of the
items keyword is a schema that all additional items must
pass in order for the keyword to validate.
Before to Draft 2020-12, you would use the
keyword to constrain additional items on a tuple. It works the same
items, only the name has changed.
Here, we'll reuse the example schema above, but set
which has the effect of disallowing extra items in the tuple.
It's ok to not provide all of the items:
false, we can't provide extra items:
You can express more complex constraints by using a non-boolean schema to constrain what value additional items can have. In that case, we could say that additional items are allowed, as long as they are all strings:
Extra string items are ok ...
... but not anything else
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
contains keyword. Just as
affects only properties in an object,
only items in an array.
Watch out! The word "unevaluated" does not mean "not evaluated by
contains." "Unevaluated" means
"not successfully evaluated", or "does not evaluate to true".
items, if you set
can disallow extra items in the array.
Here, all the values are evaluated. The schema passes validation.
But here, the schema fails validation because
specifies that no extra values should exist.
items doesn't "see inside" any instances of
oneOf in the same subschema. So in this next example,
allOf and thus fails to validate.
But if you replace
unevaluatedItems, then the same
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.)
Here the schema is "closed" to two array items. You can then later
$ref and add another item like this:
Thus, you would reference
my-tuple#closed when you need only two
items and reference
my-tuple#extended when you need three items.
items schema must be valid for every item in the array, the
contains schema only needs to validate against one or more items in
A single "number" is enough to make this pass:
But if we have no number, it fails:
All numbers is, of course, also okay:
minContains / maxContains¶
maxContains can be used with
contains to further
specify how many times a schema matches a
contains constraint. These
keywords can be any non-negative number including zero.
The length of the array can be specified using the
maxItems keywords. The value of each keyword must be a non-negative
number. These keywords work whether doing list validation or tuple-validation.
A schema can ensure that each of the items in an array is unique. Simply
uniqueItems keyword to
The empty array always passes: