Purpose: This page documents Zod's collection schema types for validating homogeneous and heterogeneous data structures. Collection schemas include arrays, tuples, sets, maps, and records, each supporting element-specific validation and size constraints.
For object schemas with named properties, see Object Schemas. For union types representing alternative schemas, see Union and Discriminated Unions.
Array schemas validate ordered collections where all elements conform to a single element schema.
Arrays support minimum, maximum, exact length, and nonempty constraints:
The $ZodArray type is defined at packages/zod/src/v4/core/schemas.ts2636-2761 Validation process:
Array.isArray() packages/zod/src/v4/core/schemas.ts2697[0], [1])Sources: packages/zod/src/v4/core/schemas.ts2636-2761 packages/zod/src/v4/classic/schemas.ts1631-1738 packages/zod/src/v4/classic/tests/array.test.ts1-120
Tuple schemas validate fixed-length arrays where each position has a specific schema.
Tuples support a rest element for additional items after fixed positions:
The $ZodTuple type is defined at packages/zod/src/v4/core/schemas.ts2763-2938 The parse method:
Sources: packages/zod/src/v4/core/schemas.ts2763-2938 packages/zod/src/v4/classic/schemas.ts1740-1893
Set schemas validate unordered collections of unique values.
Sets support the same size constraints as arrays:
The $ZodSet type is defined at packages/zod/src/v4/core/schemas.ts2940-3130 Validation:
instanceof Set packages/zod/src/v4/core/schemas.ts3029for...of to iterate set values packages/zod/src/v4/core/schemas.ts3040Sources: packages/zod/src/v4/core/schemas.ts2940-3130 packages/zod/src/v4/classic/schemas.ts1895-1975 packages/zod/src/v4/classic/tests/set.test.ts1-120
Map schemas validate collections of key-value pairs with independent schemas for keys and values.
The $ZodMap type is defined at packages/zod/src/v4/core/schemas.ts3132-3343 Validation:
instanceof Map packages/zod/src/v4/core/schemas.ts3240map.entries() packages/zod/src/v4/core/schemas.ts3251[i, "key"] packages/zod/src/v4/core/schemas.ts3258-3278[i, "value"] packages/zod/src/v4/core/schemas.ts3280-3300Sources: packages/zod/src/v4/core/schemas.ts3132-3343 packages/zod/src/v4/classic/schemas.ts1977-2048
Record schemas validate objects with dynamic keys where all keys and values conform to specific schemas.
The key schema can be:
From the example at play.ts6 partial records can work with union types:
The $ZodRecord type is defined at packages/zod/src/v4/core/schemas.ts3345-3579 Key features:
Object.keys() packages/zod/src/v4/core/schemas.ts3510values set packages/zod/src/v4/core/schemas.ts3413-3421Sources: packages/zod/src/v4/core/schemas.ts3345-3579 packages/zod/src/v4/classic/schemas.ts2050-2154 packages/zod/src/v4/core/tests/record-constructor.test.ts1-50
Sources: packages/zod/src/v4/core/schemas.ts174-3579 packages/zod/src/v4/core/checks.ts357-487
All collection schemas follow a common validation pattern with variations for their specific data structures.
Sources: packages/zod/src/v4/core/schemas.ts2636-3579 packages/zod/src/v4/core/parse.ts1-203
Size constraints are implemented as checks that attach to collection schemas.
| Method | Check Class | Min/Max | Inclusive |
|---|---|---|---|
.min(n) | $ZodCheckMinLength | Minimum | Yes |
.max(n) | $ZodCheckMaxLength | Maximum | Yes |
.length(n) / .size(n) | $ZodCheckLengthEquals | Exact | N/A |
.nonempty() | $ZodCheckMinLength (n=1) | Minimum | Yes |
$ZodCheckMinLength packages/zod/src/v4/core/checks.ts357-399:
.length or .size property is >= minimumtoo_small issue with minimum and inclusive: true$ZodCheckMaxLength packages/zod/src/v4/core/checks.ts401-443:
.length or .size property is <= maximumtoo_big issue with maximum and inclusive: true$ZodCheckLengthEquals packages/zod/src/v4/core/checks.ts445-487:
.length or .size equals exact valuetoo_small or too_big depending on actual sizeChecks use the onattach callback packages/zod/src/v4/core/checks.ts367-373 to update schema metadata:
Sources: packages/zod/src/v4/core/checks.ts357-487 packages/zod/src/v4/core/schemas.ts185-315
Each collection type uses different path formats for reporting issues.
| Collection | Path Format | Example Path | Code Location |
|---|---|---|---|
| Array | [index] | [0], [1], [2] | schemas.ts2721 |
| Tuple | [index] | [0], [1], [2] | schemas.ts2896 |
| Set | [iterationIndex] | [0], [1], [2] | schemas.ts3051 |
| Map Key | [iterationIndex, "key"] | [0, "key"], [1, "key"] | schemas.ts3265 |
| Map Value | [iterationIndex, "value"] | [0, "value"], [1, "value"] | schemas.ts3287 |
| Record | [keyName] | ["firstName"], ["age"] | schemas.ts3533 |
Paths are built by prepending the collection index/key to nested schema paths:
Sources: packages/zod/src/v4/core/schemas.ts2636-3579
Collection schemas are available in both Classic and Mini APIs with different syntaxes for applying constraints.
Method chaining on schema instances:
Methods defined in:
ZodArray packages/zod/src/v4/classic/schemas.ts1631-1738ZodSet packages/zod/src/v4/classic/schemas.ts1895-1975ZodMap packages/zod/src/v4/classic/schemas.ts1977-2048ZodRecord packages/zod/src/v4/classic/schemas.ts2050-2154Functional composition with .check():
Check functions from:
minLength, maxLength, length packages/zod/src/v4/mini/checks.tsSources: packages/zod/src/v4/classic/schemas.ts1631-2154 packages/zod/src/v4/mini/schemas.ts1010-1241
Collections support asynchronous element validation. When any element schema returns a Promise:
asyncResults arrayPromise.all() awaits all validations before returningArray async validation packages/zod/src/v4/core/schemas.ts2707-2739:
Sources: packages/zod/src/v4/core/schemas.ts2707-2739 packages/zod/src/v4/core/schemas.ts3045-3107
Records correctly handle the constructor property, which exists on all JavaScript objects:
The implementation packages/zod/src/v4/core/schemas.ts3510-3562 iterates keys and validates each without special-casing constructor.
Test coverage: packages/zod/src/v4/core/tests/record-constructor.test.ts1-50
All collection schemas accept empty collections by default:
Use .nonempty() or .min(1) to require elements.
Tuples without a rest element enforce exact length packages/zod/src/v4/core/schemas.ts2882-2886:
Zod relies on JavaScript's native Set uniqueness. No additional deduplication:
For object uniqueness, use refinements on arrays instead.
Sources: packages/zod/src/v4/core/schemas.ts2636-3579 packages/zod/src/v4/core/tests/record-constructor.test.ts1-50
Sources: packages/zod/src/v4/classic/tests/array.test.ts packages/zod/src/v4/classic/tests/object.test.ts packages/docs/content/api.mdx1152-1288
Refresh this wiki