Additional Items
In This Topic
| Draft 04 | Draft 06 | Draft 07 | Draft 2019-09 | Draft 2020-12 |
 |
|
|
|
|
Validation
5.3.1.1. Valid values
The value of "additionalItems" MUST be either a boolean or an object. If it is an object, this object MUST be a valid JSON Schema.
The value of "items" MUST be either an object or an array. If it is an object, this object MUST be a valid JSON Schema. If it is an array, items of this array MUST be objects, and each of these objects MUST be a valid JSON Schema.
5.3.1.2. Conditions for successful validation
Successful validation of an array instance with regards to these two keywords is determined as follows:
if "items" is not present, or its value is an object, validation of the instance always succeeds, regardless of the value of "additionalItems";
if the value of "additionalItems" is boolean value true or an object, validation of the instance always succeeds;
if the value of "additionalItems" is boolean value false and the value of "items" is an array, the instance is valid if its size is less than, or equal to, the size of "items".
5.3.1.4. Default values
If either keyword is absent, it may be considered present with an empty schema.
8.2.3.1. If "items" is a schema
If items is a schema, then the child instance must be valid against this schema, regardless of its index, and regardless of the value of "additionalItems".
8.2.3.2. If "items" is an array
In this situation, the schema depends on the index:
if the index is less than, or equal to, the size of "items", the child instance must be valid against the corresponding schema in the "items" array;
otherwise, it must be valid against the schema defined by "additionalItems".
Graphical Representation
As you can see from the Json Schema spec (above), the rules resulting from the combination of 'additionalItems' and 'items' keywords are quite complex and not at all intuitive.
In order to make the user interface intuitive and simple to use these values are encapsulated into "Array Items Container".
As you can see you get some unexpected results, which would be difficult to spot without a UI representation, for example the first item sets additionItems to false and has no value for items, intuitively you would expect this to disallow array items, but reading through the rules above you see that it allows anything.
| Schema Source Code |
Copy Code
|
|---|---|
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "My schema",
"additionalProperties": false,
"properties": {
"ItemsNullAdditionalItemsFalse": {
"type": "array",
"additionalItems": false
},
"ItemsNullAdditionalItemsTrue": {
"type": "array",
"additionalItems": true
},
"ItemsNullAdditionalItemsNull": {
"type": "array"
},
"ItemsNullAdditionalItemsSchema": {
"type": "array",
"additionalItems": {
"type": "string",
"maxLength": 5
}
},
"ItemsSchemaAdditionalItemsFalse": {
"type": "array",
"additionalItems": false,
"items": {}
},
"ItemsSchemaAdditionalItemsTrue": {
"type": "array",
"additionalItems": true,
"items": {}
},
"ItemsSchemaAdditionalItemsNull": {
"type": "array",
"items": {}
},
"ItemsSchemaAdditionalItemsSchema": {
"type": "array",
"additionalItems": {
"type": "string",
"maxLength": 5
},
"items": {}
},
"ItemsEmptyArrayAdditionalItemsFalse": {
"type": "array",
"additionalItems": false,
"items": []
},
"ItemsEmptyArrayAdditionalItemsTrue": {
"type": "array",
"additionalItems": true,
"items": []
},
"ItemsEmptyArrayAdditionalItemsNull": {
"type": "array",
"items": []
},
"ItemsEmptyArrayAdditionalItemsSchema": {
"type": "array",
"additionalItems": {
"type": "string",
"maxLength": 5
},
"items": []
},
"ItemsArrayWithSchemaAdditionalItemsFalse": {
"type": "array",
"additionalItems": false,
"items": [
{}
]
},
"ItemsArrayWithSchemaAdditionalItemsTrue": {
"type": "array",
"additionalItems": true,
"items": [
{}
]
},
"ItemsArrayWithSchemaAdditionalItemsNull": {
"type": "array",
"items": [
{}
]
},
"ItemsArrayWithSchemaAdditionalItemsSchema": {
"type": "array",
"additionalItems": {
"type": "string",
"maxLength": 5
},
"items": [
{}
]
}
}
}
|
|
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.
Json Schema validators make assumptions about the values of the items and additionalItems keywords
- If the items keyword is not present it is considered to contain an empty schema (which validates against everything).
- If the additionalItems keyword is not present or true then it is considered to contain an empty schema (which validates against everything).
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.
| Json Schema Source |
Copy Code
|
|---|---|
{
"$schema": "http://json-schema.org/draft-04/schema#",
"additionalItems": false,
"additionalProperties": false,
"properties": {
"Users": {
"additionalItems": false,
"items": {
"type": "string"
},
"type": "array"
}
}
}
|
|
| Valid Instance Json Document |
Copy Code
|
|---|---|
{
"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.
| Json Schema Source |
Copy Code
|
|---|---|
{
"$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"
}
}
}
|
|
| Valid Instance Json Document |
Copy Code
|
|---|---|
{
"Users": [34, "Bob", true]
}
|
|
| Valid Instance Json Document (note: it is allowable to miss values off of the end) |
Copy Code
|
|---|---|
{
"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.
| Json Schema Source |
Copy Code
|
|---|---|
{
"$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" }
]
}
}
}
|
|
| Valid Instance Json Document |
Copy Code
|
|---|---|
{
"Users": [34, "Bob", true]
}
|
|
| Valid Instance Json Document (note: it is allowable to miss values off of the end) |
Copy Code
|
|---|---|
{
"Users": [34, "Bob"]
}
|
|
| Valid Instance Json Document |
Copy Code
|
|---|---|
{
"Users": [34, "Bob", true, "Other1", "Other2"]
}
|
|
Draft 2020-12
In this version of the standard we see 'items' renamed to 'prefixItems' and 'additionalItems' renamed 'items'.
The Graphical interface takes care of this for you automatically
See Also