Skip to main content
JSON Schema provides several keywords for validating array instances.

​
minItems

Specifies the minimum number of items in an array.

​
Syntax

The value must be a non-negative integer. 
{
  "minItems": 1
}

​
Validation Rules

An array instance is valid if its size (number of elements) is greater than or equal to the specified value.

​
Default Behavior

Omitting minItems is equivalent to minItems: 0, which allows empty arrays.

​
Examples

​
Non-Empty Array

{
  "type": "array",
  "minItems": 1
}
Valid instances: 
[1]
[1, 2, 3]
["a", "b"]
Invalid instances: 
[]

​
At Least Two Items

{
  "type": "array",
  "minItems": 2
}
Valid instances: 
[1, 2]
[1, 2, 3, 4]
["a", "b"]
Invalid instances: 
[]
[1]

​
maxItems

Specifies the maximum number of items in an array.

​
Syntax

The value must be a non-negative integer. 
{
  "maxItems": 10
}

​
Validation Rules

An array instance is valid if its size (number of elements) is less than or equal to the specified value.

​
Examples

​
Limited Array Size

{
  "type": "array",
  "maxItems": 5
}
Valid instances: 
[]
[1]
[1, 2, 3, 4, 5]
Invalid instances: 
[1, 2, 3, 4, 5, 6]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

​
Single Item Array

{
  "type": "array",
  "maxItems": 1
}
Valid instances: 
[]
[42]
Invalid instances: 
[1, 2]
["a", "b"]

​
uniqueItems

Requires that all items in an array be unique.

​
Syntax

The value must be a boolean. 
{
  "uniqueItems": true
}

​
Validation Rules

  • If uniqueItems is false, the instance validates successfully (duplicates allowed)
  • If uniqueItems is true, the instance validates successfully only if all elements are unique

​
Default Behavior

Omitting uniqueItems is equivalent to uniqueItems: false, which allows duplicates.

​
Equality

Elements are considered equal according to the equality rules defined in the JSON Schema Core specification.

​
Examples

​
Unique Numbers

{
  "type": "array",
  "uniqueItems": true
}
Valid instances: 
[1, 2, 3, 4]
[]
[1]
["a", "b", "c"]
Invalid instances: 
[1, 2, 2, 3]
["a", "b", "a"]

​
Unique Objects

{
  "type": "array",
  "items": {
    "type": "object"
  },
  "uniqueItems": true
}
Valid instances: 
[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]
Invalid instances: 
[
  {"id": 1, "name": "Alice"},
  {"id": 1, "name": "Alice"}
]

​
Mixed Type Array

{
  "type": "array",
  "uniqueItems": true
}
Valid instances: 
[1, "1", true, null]
[{"a": 1}, {"a": 2}]
Invalid instances: 
[1, 1]
[true, true]
[null, null]

​
Combining Array Keywords

Multiple array validation keywords can be used together to define precise constraints.

​
Size Range

{
  "type": "array",
  "minItems": 1,
  "maxItems": 10
}
This validates arrays with 1 to 10 items: 
[1]
[1, 2, 3]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

​
Unique Tags

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}
This validates an array of 1-5 unique strings: 
["javascript"]
["javascript", "typescript", "python"]
Invalid: 
[]                                    // Too few items
["js", "js"]                          // Not unique
["a", "b", "c", "d", "e", "f"]       // Too many items

​
Coordinates (Pair)

{
  "type": "array",
  "items": {
    "type": "number"
  },
  "minItems": 2,
  "maxItems": 2
}
This validates exactly 2 numeric coordinates: 
[10.5, 20.3]
[-73.935242, 40.730610]
Invalid: 
[10]           // Too few
[10, 20, 30]   // Too many

​
Team Members

{
  "type": "object",
  "properties": {
    "team": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "integer"},
          "name": {"type": "string"}
        },
        "required": ["id", "name"]
      },
      "minItems": 2,
      "maxItems": 10,
      "uniqueItems": true
    }
  }
}
Valid instance: 
{
  "team": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"}
  ]
}

​
Fixed Size Array

{
  "type": "array",
  "minItems": 3,
  "maxItems": 3
}
This validates arrays with exactly 3 items: 
[1, 2, 3]
["a", "b", "c"]
[true, false, null]

​
Optional Array

{
  "type": "array",
  "maxItems": 5,
  "uniqueItems": true
}
This allows empty arrays or up to 5 unique items: 
[]
[1]
[1, 2, 3, 4, 5]

​
Use Cases

  • minItems: Ensure at least one selection (e.g., order items, selected options)
  • maxItems: Limit number of tags, attachments, or choices
  • uniqueItems: Prevent duplicate selections, tags, or IDs
  • Combined: Define precise constraints like “select 3-5 unique categories”

Build docs developers (and LLMs) love

Get started for freeTalk to us