Input validation
Validate request payloads containing lists of strings, numbers, or structured records.
Zod · Module
.array
.array() turns an existing Zod schema into an array schema, so each item is validated against that schema. Use array length methods such as .min(), .max(), .length(), and .nonempty() for collection constraints.
How it works
.array() creates a new array schema whose elements must satisfy the schema it is called on. Array-specific constraints can then be chained, while the order of .array() and methods such as .optional() changes the resulting schema; the inner schema is available through .unwrap().
Syntax
elementSchema.array()Parameters
| Name | Type | Description |
|---|---|---|
elementSchema | Zod schema | The schema that every array element must satisfy. |
Returns
A Zod array schema whose elements conform to the receiver or supplied element schema.
Key points
- Create an array schema with
z.array(elementSchema)or use the equivalentelementSchema.array()convenience method. - The two supported declarations are equivalent: the standalone constructor and the element schema's
.array()method. - Call
.unwrap()on an array schema when you need the schema governing individual elements. - Use
.nonempty()to require at least one element. - Use
.min(n)to enforce a minimum array length. - Use
.max(n)to enforce a maximum array length. - Use
.length(n)when the array must contain exactly a specified number of items.
Example: Validate a non-empty string array
import { z } from "zod";
const tags = z.array(z.string()).min(1);
const result = tags.safeParse(["typescript", "zod"]);
if (result.success) {
console.log(result.data);
}Defines a schema for a non-empty array whose elements are strings, then safely validates an example value.
When to use it
Cardinality rules
Require collection sizes such as non-empty tags or bounded batches.
Schema composition
Reuse an existing element schema while composing nested array types.
Interview questions
QHow do you define an array of strings in Zod?
Use either z.array(z.string()) or z.string().array(); both define an array whose items are strings. The method form is a convenience attached to the element schema.
Follow-up: What changes between z.string().optional().array() and z.string().array().optional()? The first permits undefined elements, while the second permits the entire array to be undefined.
QHow can an array's length be constrained?
Array schemas support .min(), .max(), and .length() for lower, upper, and exact item counts. .nonempty() requires at least one item.
Follow-up: How would you require between five and ten items? Chain .min(5).max(10) on the array schema.
QHow do you access an array schema's element schema?
Use .unwrap() to retrieve the schema used for each array element. For example, z.array(z.string()).unwrap() returns the string schema.
Follow-up: Why is this useful? It lets code inspect or reuse the inner schema without reconstructing the array definition.
Related
z.arrayZodArray.unwrap().nonempty().min().max().length()