Array input validation
Validate request payloads containing lists of primitive values or structured records.
Zod · Function
z.array
z.array creates a schema for arrays whose elements conform to a supplied Zod schema. It also supports array-length constraints and readonly output types.
How it works
z.array builds an array schema from an element schema. Each array item is checked against that inner schema, while array-specific methods can constrain the number of items or produce a readonly array type.
Syntax
z.array(element)Parameters
| Name | Type | Description |
|---|---|---|
element | Zod schema | The schema that every element in the array must satisfy. |
Returns
An array schema whose elements are validated by the supplied element schema.
Key points
- Pass the desired element schema to z.array; the chainable .array() form is equivalent.
- nonempty requires at least one element.
- min sets the smallest permitted array length.
- max sets the largest permitted array length.
- readonly changes the inferred array type to readonly while retaining element validation.
Common mistakes
- Use unwrap() when you need to retrieve the schema used to validate each array element.
- length enforces an exact item count; it is not a minimum or maximum constraint.
Example: Validate a bounded string array
import { z } from "zod";
const Tags = z.array(z.string()).min(1).max(3);
const result = Tags.safeParse(["typescript", "zod"]);
if (result.success) {
console.log(result.data);
}Creates a schema for an array of strings, requires at least one item, and limits the array to three items.
When to use it
Length constraints
Enforce collection cardinality such as nonempty, bounded, or exact-size lists.
Readonly collections
Expose immutable array types after validation.
Interview questions
QHow do you define an array of strings?
z.array(z.string()) creates a schema whose input must be an array and whose elements must each satisfy z.string(). The equivalent method form is z.string().array().
Follow-up: How would you require between two and five elements? Chain .min(2).max(5) onto the array schema.
QHow can array length be constrained?
Use .min(n) for a lower bound, .max(n) for an upper bound, and .length(n) for an exact count. For example, z.array(z.string()).min(5) requires five or more strings.
Follow-up: How do you reject an empty array without specifying a numeric lower bound? Use .nonempty().
QHow can you inspect the element schema?
The schema's unwrap() method returns the inner element schema. For const stringArray = z.array(z.string()), stringArray.unwrap() yields the string schema.
Follow-up: What type does readonly() produce for a string array? It produces a readonly string[] type.
Related
z.string().array()unwrap()nonempty()min()max()length()readonly()z.tuple()