Tuple Validation with prefixItems in JSON Schema

Tuple Schemas: Fixed-Position Arrays

Unlike regular arrays where every element follows the same schema, tuples define a specific schema for each position. JSON Schema Draft 2020-12 uses the prefixItems keyword for this purpose (older drafts used items as an array).

Example: Coordinate Pair

Given a sample like:

[40.7128, -74.0060]

A tuple schema looks like:

{
  "type": "array",
  "prefixItems": [
    { "type": "number", "minimum": -90, "maximum": 90 },
    { "type": "number", "minimum": -180, "maximum": 180 }
  ],
  "items": false
}

• prefixItems defines the schema for each position: index 0 is latitude, index 1 is longitude.
• items: false prevents any additional elements beyond the defined positions. Without this, extra elements would be allowed.

Example: Mixed-Type Record

Tuples are also useful for CSV-like records:

["Alice", 30, true]

Schema:

{
  "type": "array",
  "prefixItems": [
    { "type": "string" },
    { "type": "integer", "minimum": 0 },
    { "type": "boolean" }
  ],
  "items": false,
  "minItems": 3,
  "maxItems": 3
}

Adding minItems and maxItems equal to the number of prefixItems entries enforces an exact length.

Generator Behavior

Most generators produce a standard items schema (homogeneous array) by default. Tuple generation typically requires the generator to detect that the array has a fixed length with differently typed positions. If the generator does not detect this pattern, you can convert the output manually by replacing items with prefixItems.

When to Use Tuples

• Coordinates: [lat, lng] or [x, y, z]
• Ranges: [start, end] for dates, numbers, or pagination
• Heterogeneous records: Rows from CSV imports where each column has a distinct type
• Return values: Functions that return multiple values in a fixed order

Draft Compatibility

• Draft 2020-12: Use prefixItems for tuple schemas.
• Draft 7 / 2019-09: Use items as an array plus additionalItems: false.

Be mindful of which draft your validator supports when choosing the syntax.