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 Annotation
Applies To Array
Base Dialect 2019-09
Changed In Draft 6
Introduced In Draft 1
Vocabulary Applicator
Specification https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.section.9.3.1.1
Metaschema https://json-schema.org/draft/2019-09/meta/applicator
Official Tests draft2019-09/items.json
Default {}
Annotation Number Boolean If set to a schema, a boolean true if it applied to every item of the instance, otherwise the largest index to which this keyword applied its subschema, or a boolean true if it was applied to every item of the instance Hint: Use the jsonschema validate command to collect annotations from the command-line
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. Whether this keyword was evaluated against any item of the array instance is reported using annotations.

  • 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. The annotation reports the largest index to which a subschema was applied, or true if it was applied to every item.

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": "https://json-schema.org/draft/2019-09/schema",
  "items": { "type": "number" }
}
Valid An array value that only consists of number items is valid Instance 
[ 1, -3.4, 54 ]
Annotations 
{ "keyword": "/items", "instance": "", "value": true }
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": "https://json-schema.org/draft/2019-09/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 ]
Annotations 
{ "keyword": "/items", "instance": "", "value": true }
Valid An array value with additional items beyond the tuple is valid Instance 
[ false, 35, "foo", "bar" ]
Annotations 
{ "keyword": "/items", "instance": "", "value": 1 }
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": "https://json-schema.org/draft/2019-09/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 ]
Annotations 
{ "keyword": "/items", "instance": "", "value": true }
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" ]
Annotations 
{ "keyword": "/items", "instance": "", "value": 1 }
{ "keyword": "/additionalItems", "instance": "", "value": true }
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"