Array Validation

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”

Core Keywords

Applicator Keywords

Validation Keywords

Meta-Data

minItems

Syntax

Validation Rules

Default Behavior

Examples

Non-Empty Array

At Least Two Items

maxItems

Syntax

Validation Rules

Examples

Limited Array Size

Single Item Array

uniqueItems

Syntax

Validation Rules

Default Behavior

Equality

Examples

Unique Numbers

Unique Objects

Mixed Type Array

Combining Array Keywords

Size Range

Unique Tags

Coordinates (Pair)

Team Members

Fixed Size Array

Optional Array

Use Cases

​minItems

​Syntax

​Validation Rules

​Default Behavior

​Examples

​Non-Empty Array

​At Least Two Items

​maxItems

​Syntax

​Validation Rules

​Examples

​Limited Array Size

​Single Item Array

​uniqueItems

​Syntax

​Validation Rules

​Default Behavior

​Equality

​Examples

​Unique Numbers

​Unique Objects

​Mixed Type Array

​Combining Array Keywords

​Size Range

​Unique Tags

​Coordinates (Pair)

​Team Members

​Fixed Size Array

​Optional Array

​Use Cases

minItems

Syntax

Validation Rules

Default Behavior

Examples

Non-Empty Array

At Least Two Items

maxItems

Syntax

Validation Rules

Examples

Limited Array Size

Single Item Array

uniqueItems

Syntax

Validation Rules

Default Behavior

Equality

Examples

Unique Numbers

Unique Objects

Mixed Type Array

Combining Array Keywords

Size Range

Unique Tags

Coordinates (Pair)

Team Members

Fixed Size Array

Optional Array

Use Cases