Draft 04	Draft 06	Draft 07	Draft 2019-09	Draft 2020-12

The Array Item Container determines the validation rules applied to an array of values in the JSON instance document.

The index values on the 'Array Item' nodes (shown in square brackets []) indicate the index in the instance array that the schema apply's to.

If the index value covers a range (e.g. [3-n]) then this schema will be used to validate all array items in the instance array from index 3 and above, and is referred to as the 'Additional Items' node.

To add a schema to validate the an item at a given array index , use the context menu 'Add Array Items -> Add Item ...' from the Parent Schema or the context menu on the Array Item Container itself.

The order of the items can be changed by dragging them to the desired position (if an 'Additional Items' node exists it is always the last node, and can not be dragged).

Array Item Validation.

The items and additionalItems keywords control what kind of objects can appear in an instance array. They are closely interrelated and subtlety effect the validation applied. Broadly speaking there are 2 types of validation we will call them List and Tuple validation.

List Validation

When List validation is used, a schema is defined and all the objects in the array must validate against this schema. This is the simplest and mostly widely used form of array validation.

List validation is used when the items keyword contains a single schema object.

When this is the case the property additionalItems is ignored.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}

{
    "Users": ["Alice","Bob", "Eve"]
}

Tuple Validation

Tuple validation allows you to provide a schema to validate each item in the instance array.

Tuple validation is used when the items property contains an array of schema objects.

Each item in the items array validates an object in the instance array at the corresponding index.

• It is acceptable for the instance array to contain less items than are specified in the items array.
• If the instance array contains more items than their are entries in the items array then the additionalItems keyword affects how these additional items are validated.
  • If the additionalItems keyword is 'true', then any additional array items in the instance array are allowed (regardless of there type or value).
  • If the additionalItems keyword is 'false', then additional array items in the instance array are NOT allowed.
  • If the additionalItems keyword contains a schema, then additional array items in the instance array must validate against this schema.

Tuple Example 1

In this example the schema specifies the schemas for first 3 items in the array, if more than 3 items appear in the instance array then it is an error, however it is acceptable for the array to contain less than 3 items as long as the ones that are present validate against the appropriate schema.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}

{
    "Users": [34, "Bob", true]
}

{
    "Users": [34, "Bob"]
}

Tuple Example 2

In this example the schema is specified for the first 3 items in the array, additionally a schema is provided for any additional array items (note the [3-n] indicator).

The first 3 objects in the instance array must validate against the corresponding schema, but any additional items must validate against the [3-n] schema.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "type": "array",
            "additionalItems": {
                "type": "string"
            },
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]
        }
    }
}

{
    "Users": [34, "Bob", true]
}

{
    "Users": [34, "Bob"]
}

{
    "Users": [34, "Bob", true, "Other1", "Other2"]
}