> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dottxt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Array

> Ordered lists with item schemas and length constraints.

Use `"type": "array"` for ordered lists.

## Core array keywords

| Keyword                 | What it does                              |
| ----------------------- | ----------------------------------------- |
| `prefixItems`           | Positional schemas for tuple-style arrays |
| `items`                 | Schema for each array element             |
| `minItems` / `maxItems` | Bounds array length                       |

<Note>
  `contains`, `minContains`, `maxContains`, `uniqueItems` and `unevaluatedItems` are not supported right now.
  If you have a use case that requires them, reach out to us.
</Note>

## Example

<CodeGroup>
  ```json JSON Schema theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "type": "object",
    "properties": {
      "values": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "minItems": 1,
        "maxItems": 5
      }
    },
    "required": ["values"],
    "additionalProperties": false
  }
  ```

  ```python Pydantic theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from typing import Annotated
  from pydantic import BaseModel, ConfigDict, Field

  class Payload(BaseModel):
      model_config = ConfigDict(extra="forbid")

      values: Annotated[list[float], Field(min_length=1, max_length=5)]
  ```

  ```typescript Zod theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import { z } from "zod";

  const payloadSchema = z
    .object({
      values: z.array(z.number()).min(1).max(5),
    })
    .strict();
  ```
</CodeGroup>

For capped payload size, always set `maxItems`. The default value of `minItems` is 0.

## `prefixItems`

Use `prefixItems` for tuple-style arrays where position matters:

<CodeGroup>
  ```json JSON Schema theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "type": "object",
    "properties": {
      "metric": {
        "type": "array",
        "prefixItems": [
          { "type": "string", "enum": ["latency_ms", "error_count"] },
          { "type": "number", "minimum": 0 }
        ],
        "items": false
      }
    },
    "required": ["metric"],
    "additionalProperties": false
  }
  ```

  ```python Pydantic theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from typing import Annotated, Literal
  from pydantic import BaseModel, ConfigDict, Field

  class Payload(BaseModel):
      model_config = ConfigDict(extra="forbid")

      metric: tuple[Literal["latency_ms", "error_count"], Annotated[float, Field(ge=0)]]
  ```

  ```typescript Zod theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import { z } from "zod";

  const payloadSchema = z
    .object({
      metric: z.tuple([z.enum(["latency_ms", "error_count"]), z.number().min(0)]),
    })
    .strict();
  ```
</CodeGroup>

This example enforces a two-element array: a metric name followed by a numeric value.

## Related

* [Object reference](/json-schema/reference/object)
* [Bounded Arrays cookbook](/json-schema/bounded-arrays)