Arrays

Here we show how to specify collections of JSON types using possibly nested JSON Schemas.

Array Schemas

Arrays are used to represent ordered sets of values, such as the following sequence of strings:

["Chilean", "Argentinean", "Peruvian", "Colombian"]

In this section we specify array's main charasteristics and restrictions that may apply to them using a single JSON Schema document.

First of all, we want to ensure that the document we are validating is an array using the type restriction. This is the basic array schema:

{
 "type": "array"
}

This schema specifyies arrays and no other JSON documents. For example the following document does not validate against the schema:

{
 "nation1": "chilean", 
 "nation2": "argentinean",
 "this": "is",
 "not": "an",
 "keyword": "array"
 }

On the other hand, the following JSON does validate against the schema above: 

["Chilean", "Argentinean", "this", "is", "an", "array"]

Restrictions

We can restrict the contents of an array using a JSON Schema. For example, if we want to be sure that the items of the array are strings and that we could have at most 3 items we could use the following schema:

{
 "type": "array",
 "maxItems": 3,
 "items": {
           "type": "string"
          }
}

The following JSON document would validate again the schema:

["Chilean", "Argentinean"]

This one would not validate since it has more than 3 elements:

["Chilean", "Argentinean", "Peruvian", "Colombian"]

A JSON Schema for an array can be seen as set of restrictions that must apply on the elements of the array. In the next sections we specificate each restriction and when a JSON document validates against these restrictions.

Item Restriction

We use these restrictions to restrict the elements of the array. We have two ways of doing this.

The first is to enforce that all the elements of an array must validate against a given schema, as in the following example:

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

In this case, we are asking that every element of the array must be an integer. For example, this array validates against the schema

[3, 1, 4, 5]

But this one does not

[3, "one", 4, 5]

The second way of restricting the elements is to specify a JSON Schema for each element in the array. The following schema is an example of the second use of the items restriction: 

{
 "type": "array",
 "items" : [{
          "type": "string"
         },
         {
          "type": "integer"
         },
         {
          "type": "boolean"
         }
         ]
}

In this case, we are asking that the first element must be a string, the second one an integer and the third one a boolean. For example, this array validates against the schema

["Chile", 1, true ]

But this one does not

["Chile", "one", 4]

Note that the default behaviour of JSON Schema allows us to have fewer items, as long as the corresponding (sub)schemas are satisfied. For instance, the array 

["Chile", 4]

does validate against the schema above. The same is true if we have more items. Namely, the following array is valid against the schema above:

["Chile", 4, true, "Argentina", "Brazil"]

Additional Items

This restriction specifies if the array can contain items which are not specified in the schema. Here we have an example of this kind of restriction

{
 "type": "array",
 "items" : [{
          "type": "string"
         },
         {
          "type": "integer"
         },
         {
          "type": "boolean"
         }
         ],
 "additionalItems": false       
}

In this example, we are asking that the first element must be a string, the second one an integer and the third one a boolean. But we cannot have any more items than these three. Here have JSON document that validates against this schema

["Chile", 1, true]

But this one does not validate, because there is an additional item. 

["Chile", 1, true, 2]

As illustrated above, by default JSON Schema behaves as if the additionalItems parameter is set to true.

Item Quantity

We can also specify the amount of items in an array. We use "minItems": n to specify that the array must have at least n elements, and "maxItems": n to specify that the array cannot have more than n elements. Here we have an example of this restriction

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

As we can see, we are specifying arrays with at least 2 elements and no more than 5. For example this document validates against the schema

["Chile", 16.000.000, "San Francisco", 800.000]

But this one does not

["Chile", 16.000.000, "San Francisco", 800.000, "London", 9.000.000]

Uniqueness

We use this restriction if we want all elements of an array to be different. The following schema specifies an array in which all documents are different:

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

For example this document validates against the schema

[1, 3, 5, 7]

But this one does not, 

[1, 3, 5, 3]

Formal Specification

The correct grammar for these schemas is as follows: 

 arrSch:= "type": "array" (, arrRes)*

Here arrRes is a restriction for the type array such that every arrRes must be different from each other and occurs no more than one time each. Each of these restrictions is defined as follows: 

 arrRes := items | additems | minitems | maxitems  | unique
 items := ( sameitems |  varitems )
 sameitems := "items": { JSch }
 varitems := "items": [{ JSch }(,{ JSch })*] 
 additems :=  "additionalItems": (bool | { JSch })
 minitems := "minItems": n
 maxitems := "maxItems": n
 unique := "uniqueItems": bool

Here n is a natural number and bool is either true or false.

Formal Validation

Let A be an Array Schema and J a JSON document. We say that J validates against A if for each key:value pair k in A one of the following holds: