Position-specific data
Representing structured records encoded as arrays, such as [name, identifier, active].
Zod · Function
z.tuple
z.tuple defines a tuple schema whose positions can use different Zod schemas. An optional rest schema allows additional values after the fixed prefix.
How it works
Use z.tuple to declare an array whose positions have distinct schemas. Zod validates the required items in order and infers a corresponding TypeScript tuple; passing a second schema adds a variadic rest portion after the fixed items.
Syntax
z.tuple(items, rest?)Parameters
| Name | Type | Description |
|---|---|---|
items | ZodType[] | Array of schemas for the tuple's fixed positional elements. |
rest | ZodType | Optional schema applied to additional elements after the fixed items. |
Returns
A Zod tuple schema that validates fixed positional elements and, when supplied, additional elements against the rest schema.
Key points
- A tuple models positional data: its length and the schema expected at each fixed index are declared up front.
- Create a tuple by passing an array of element schemas to z.tuple.
- Zod's inferred type follows the declared order, producing a TypeScript tuple whose element types match the schemas.
- Supply a second schema to permit a repeated rest section after the fixed prefix.
- Use .readonly() when the tuple should expose a readonly TypeScript result.
Common mistakes
- A second schema is interpreted as a rest schema, so values after the fixed prefix may repeat that schema and the inferred type becomes variadic.
Example: Validate a fixed-length tuple
import { z } from "zod";
const UserTuple = z.tuple([z.string(), z.number()]);
const user = UserTuple.parse(["Ada", 37]);
console.log(user); // ["Ada", 37]Defines and validates a two-element tuple containing a string followed by a number.
When to use it
Variadic arguments
Accepting a required prefix followed by zero or more values of one type.
Typed parsing
Deriving a precise TypeScript tuple type from runtime validation rules.
Interview questions
QWhat does z.tuple do?
z.tuple accepts an ordered list of schemas, with each schema validating the value at its corresponding index. Unlike an array schema, it models a fixed positional structure and infers a TypeScript tuple.
Follow-up: How would you allow additional values? Pass a second schema, such as z.tuple([z.string()], z.number()), to model a string followed by zero or more numbers.
QHow do you define a variadic tuple?
The first argument defines the fixed prefix. An optional second schema defines the variadic portion, producing an inferred type like [string, ...number[]].
Follow-up: What is the difference from z.array(z.number())? The tuple preserves the required first position and permits only numbers in subsequent positions.
QHow does a tuple differ from an array?
Each position can use a different schema, so z.tuple([z.string(), z.number(), z.boolean()]) represents [string, number, boolean]. Parsing checks both the order and the value schemas.
Follow-up: How can the resulting tuple be made immutable at the type level? Apply .readonly(), which yields a readonly tuple type.
Related
z.arrayz.inferz.readonlyz.union