JSON Schema for OpenAPI course

Looking to master JSON Schema for OpenAPI?

A 9+ hour course taught by a member of the JSON Schema Technical Steering Committee

Take the Video Course Also check out our O'Reilly book

items : Schema | Array<Schema>

items

Schema | Array<Schema>

If set to a schema, validation succeeds if each element of the instance validates against it, otherwise validation succeeds if each element of the instance validates against the schema at the same position, if any

Value This keyword must be set to a valid JSON Schema or to a non-empty array, where each item is a valid JSON Schema Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
Kind Applicator
Applies To Array
Base Dialect Draft 6
Changed In 2020-12
Introduced In Draft 1
Vocabulary Validation
Specification https://json-schema.org/draft-06/draft-wright-json-schema-validation-01#rfc.section.6.9
Metaschema http://json-schema.org/draft-06/schema#
Official Tests draft6/items.json
Default {}
Annotation None
Affected By
Affects
Also See

The items keyword is used to validate array items and has two different modes of operation depending on the type of its value:

  • Schema: When set to a schema, items validates that all items in the array instance validate against the given subschema.

  • Array: When set to an array of schemas, items validates each item in the array instance against the subschema at the corresponding position. Items beyond the length of the items array can be validated using the additionalItems keyword.

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 constrains array instances to consist of number items Schema 
{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "items": { "type": "number" }
}
Valid An array value that only consists of number items is valid Instance 
[ 1, -3.4, 54 ]
Valid An empty array value is valid Instance 
[]
Invalid An array value that includes a non-number item is invalid Instance 
[ 1, -3.4, 54, "foo" ]
Valid A non-array value is valid Instance 
"Hello World"
A schema that constrains array instances to start with a boolean item followed by a number item Schema 
{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "items": [ { "type": "boolean" }, { "type": "number" } ]
}
Valid An array value that consists of a boolean item followed by a number item is valid Instance 
[ false, 35 ]
Valid An array value with additional items beyond the tuple is valid Instance 
[ false, 35, "foo", "bar" ]
Invalid An array value where the first item is not a boolean is invalid Instance 
[ "not a boolean", 35 ]
Invalid An array value where the second item is not a number is invalid Instance 
[ false, "not a number" ]
Valid An empty array value is valid Instance 
[]
Valid A non-array value is valid Instance 
"Hello World"
A schema that constrains array instances to start with a boolean item followed by a number item, with only string items allowed beyond that Schema 
{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "items": [ { "type": "boolean" }, { "type": "number" } ],
  "additionalItems": { "type": "string" }
}
Valid An array value that consists of a boolean item followed by a number item is valid Instance 
[ false, 35 ]
Valid An array value that consists of a boolean item followed by a number item and string items is valid Instance 
[ false, 35, "foo", "bar" ]
Invalid An array value that consists of a boolean item followed by a number item and non-string items is invalid Instance 
[ false, 35, { "foo": "bar" } ]
Valid An empty array value is valid Instance 
[]
Valid A non-array value is valid Instance 
"Hello World"