Arrays are used for ordered elements. In JSON, each element in an arraymay be of a different type.

schema

{"type":"array"}

data

[1,2,3,4,5]

compliant to schema

data

[3,"different",{"types":"of values"}]

compliant to schema

data

{"Not":"an array"}

not compliant to schema

There are two ways in which arrays are generally used in JSON:

• List validation: a sequence of arbitrary length where each item matches the sameschema.
• 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'stuple).

Items

List validation is useful for arrays of arbitrary length where each itemmatches the same schema. For this kind of array, set theitemskeywordto a single schema that will be used to validate all of the items in thearray.

In the following example, we define that each item in an array is anumber:

schema

{"type":"array","items":{"type":"number"}}

data

[1,2,3,4,5]

compliant to schema

A single "non-number" causes the whole array to be invalid:

data

[1,2,"3",4,5]

not compliant to schema

The empty array is always valid:

data

[]

compliant to schema

Tuple validation

Tuple validation is useful when the array is a collection of items whereeach has a different schema and the ordinal index of each item ismeaningful.

For example, you may represent a street address such as1600 Pennsylvania Avenue NW as a 4-tuple of the form:

data

[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 fixedset of values.
• direction: The city quadrant of the address. Should be a stringfrom a different set of values.

To do this, we use theprefixItems keyword.prefixItems is an array,where each item is a schema that corresponds to each index of thedocument's array. That is, an array where the first element validatesthe first element of the input array, the second element validates thesecond element of the input array, etc.

Draft-specific info

In Draft 4 - 2019-09, tuple validation was handled by an alternate form of theitems keyword. Whenitems was an array of schemas instead of a single schema, it behaved the wayprefixItems behaves.

Here's the example schema:

schema

{"type":"array","prefixItems":[{"type":"number"},{"type":"string"},{"enum":["Street","Avenue","Boulevard"]},{"enum":["NW","NE","SW","SE"]}]}

data

[1600,"Pennsylvania","Avenue","NW"]

compliant to schema

"Drive" is not one of the acceptable street types:

data

[24,"Sussex","Drive"]

not compliant to schema

This address is missing a street number:

data

["Palais de l'Élysée"]

not compliant to schema

It's okay to not provide all of the items:

data

[10,"Downing","Street"]

compliant to schema

And, by default, it's also okay to add additional items to end:

data

[1600,"Pennsylvania","Avenue","NW","Washington"]

compliant to schema

Additional Items

Theitems keyword can be used to control whether it's valid to haveadditional items in a tuple beyond what is defined inprefixItems. Thevalue of theitems keyword is a schema that all additional items mustpass in order for the keyword to validate.

Draft 4 - 2019-09

Before to Draft 2020-12, you would use theadditionalItemskeyword to constrain additional items on a tuple. It works the sameasitems, only the name has changed.

Draft 6 - 2019-09

In Draft 6 - 2019-09, theadditionalItems keyword is ignored ifthere is not a "tuple validation"items keyword present in thesame schema.

Here, we'll reuse the example schema above, but setitems tofalse,which has the effect of disallowing extra items in the tuple.

schema

{"type":"array","prefixItems":[{"type":"number"},{"type":"string"},{"enum":["Street","Avenue","Boulevard"]},{"enum":["NW","NE","SW","SE"]}],"items":false}

data

[1600,"Pennsylvania","Avenue","NW"]

compliant to schema

It's ok to not provide all of the items:

data

[1600,"Pennsylvania","Avenue"]

compliant to schema

But, sinceitems isfalse, we can't provide extra items:

data

[1600,"Pennsylvania","Avenue","NW","Washington"]

not compliant to schema

You can express more complex constraints by using a non-boolean schemato constrain what value additional items can have. In that case, wecould say that additional items are allowed, as long as they are allstrings:

schema

{"type":"array","prefixItems":[{"type":"number"},{"type":"string"},{"enum":["Street","Avenue","Boulevard"]},{"enum":["NW","NE","SW","SE"]}],"items":{"type":"string"}}

Extra string items are ok ...

data

[1600,"Pennsylvania","Avenue","NW","Washington"]

compliant to schema

... but not anything else

data

[1600,"Pennsylvania","Avenue","NW",20500]

not compliant to schema

Unevaluated Items

New in draft 2019-09

TheunevaluatedItems keyword is useful mainly when you want to addor disallow extra items to an array.

unevaluatedItems applies to any values not evaluated by anitems,prefixItems, orcontains keyword. Just asunevaluatedPropertiesaffects onlyproperties in an object,unevaluatedItems affectsonlyitems in an array.

Like withitems, if you setunevaluatedItems tofalse, youcan disallow extra items in the array.

schema

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

Here, all the values are evaluated. The schema passes validation.

data

["foo",42]

compliant to schema

But here, the schema fails validation because"unevaluatedItems": falsespecifies that no extra values should exist.

data

["foo",42,null]

not compliant to schema

Note thatitems doesn't "see inside" anyinstances ofallOf,anyOf, oroneOf in the samesubschema. So in this next example,items ignoresallOf and thus fails to validate.

schema

{"allOf":[{"prefixItems":[{"type":"boolean"},{"type":"string"}]}],"items":{"const":2}}

data

[true,"a",2]

not compliant to schema

But if you replaceitems withunevaluatedItems, then the samearray validates.

schema

{"allOf":[{"prefixItems":[{"type":"boolean"},{"type":"string"}]}],"unevaluatedItems":{"const":2}}

data

[true,"a",2]

compliant to schema

You can also make a "half-closed" schema: something useful when youwant to keep the first two arguments, but also add more in certainsituations. ("Closed" to two arguments in some places, "open" tomore arguments when you need it to be.)

schema

{"$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 lateruse$ref and add another item like this:

schema

{"$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 referencemy-tuple#closed when you need only twoitems and referencemy-tuple#extended when you need three items.

Contains

New in draft 6

While theitems schema must be valid for every item in the array, thecontains schema only needs to validate against one or more items inthe array.

schema

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

A single "number" is enough to make this pass:

data

["life","universe","everything",42]

compliant to schema

But if we have no number, it fails:

data

["life","universe","everything","forty-two"]

not compliant to schema

All numbers is, of course, also okay:

data

[1,2,3,4,5]

compliant to schema

minContains / maxContains

New in draft 2019-09

minContains andmaxContains can be used withcontains to furtherspecify how many times a schema matches acontains constraint. Thesekeywords can be any non-negative number including zero.

schema

{"type":"array","contains":{"type":"number"},"minContains":2,"maxContains":3}

FailsminContains

data

["apple","orange",2]

not compliant to schema

data

["apple","orange",2,4]

compliant to schema

data

["apple","orange",2,4,8]

compliant to schema

FailsmaxContains

data

["apple","orange",2,4,8,16]

not compliant to schema

Length

The length of the array can be specified using theminItems andmaxItems keywords. The value of each keyword must be a non-negativenumber. These keywords work whether doinglist validation ortuple-validation.

schema

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

data

[]

not compliant to schema

data

[1]

not compliant to schema

data

[1,2]

compliant to schema

data

[1,2,3]

compliant to schema

data

[1,2,3,4]

not compliant to schema

Uniqueness

A schema can ensure that each of the items in an array is unique. Simplyset theuniqueItems keyword totrue.

schema

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

data

[1,2,3,4,5]

compliant to schema

data

[1,2,3,3,4]

not compliant to schema

The empty array always passes:

data

[]

compliant to schema