Collection Schemas

Relevant source files

• packages/docs/content/api.mdx
• packages/docs/content/json-schema.mdx
• packages/zod/src/v4/classic/tests/catch.test.ts
• packages/zod/src/v4/classic/tests/function.test.ts
• packages/zod/src/v4/classic/tests/index.test.ts
• packages/zod/src/v4/classic/tests/optional.test.ts
• packages/zod/src/v4/classic/tests/partial.test.ts
• packages/zod/src/v4/classic/tests/pickomit.test.ts
• packages/zod/src/v4/classic/tests/record.test.ts
• packages/zod/src/v4/classic/tests/tuple.test.ts
• packages/zod/src/v4/core/tests/extend.test.ts
• packages/zod/src/v4/core/tests/record-constructor.test.ts
• packages/zod/src/v4/mini/tests/index.test.ts

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

Array schemas validate ordered collections where all elements conform to a single element schema.

Basic Usage

Size Constraints

Arrays support minimum, maximum, exact length, and nonempty constraints:

Implementation

The $ZodArray type is defined in the core schema system. Validation process:

1. Type check: Verifies input via Array.isArray().
2. Element validation: Iterates through elements, parsing each against the element schema.
3. Path tracking: Issues include array index in path (e.g., [0], [1]) packages/zod/src/v4/classic/tests/index.test.ts218-220
4. Size checks: Applied after element validation.

Sources: packages/docs/content/api.mdx1152-1200 packages/zod/src/v4/classic/tests/index.test.ts217-221

---

Tuple Schemas

Tuple schemas validate fixed-length arrays where each position has a specific schema.

Basic Tuples

Rest and Optional Elements

Tuples support rest elements for additional items and trailing optional elements:

Implementation

The $ZodTuple type handles positional validation:

1. Length validation: Checks if the input array length matches the fixed positions (taking into account optional/defaulted items) packages/zod/src/v4/classic/tests/tuple.test.ts26-39
2. Fixed positions: Parses each position against its specific schema.
3. Rest elements: If .rest() is defined, validates all remaining elements against the rest schema packages/zod/src/v4/classic/tests/tuple.test.ts109-112 .

Sources: packages/zod/src/v4/classic/tests/tuple.test.ts1-205 packages/docs/content/api.mdx1202-1250

---

Set Schemas

Set schemas validate unordered collections of unique values.

Basic Sets

Size Constraints

Sets support the same size constraints as arrays:

Implementation

The $ZodSet type validation:

1. Type check: Verifies instanceof Set.
2. Element iteration: Iterates set values and validates each against the value schema.
3. Path tracking: Uses numeric indices based on iteration order for error reporting.

Sources: packages/docs/content/api.mdx1252-1288 packages/docs/content/json-schema.mdx70

---

Map Schemas

Map schemas validate collections of key-value pairs with independent schemas for keys and values.

Basic Maps

Size Constraints

Implementation

The $ZodMap type validation:

1. Type check: Verifies instanceof Map.
2. Entry iteration: Iterates through entries, validating keys and values independently.
3. Path tracking: Parses keys with path [i, "key"] and values with path [i, "value"].

Sources: packages/docs/content/api.mdx1290-1310 packages/docs/content/json-schema.mdx69

---

Record Schemas

Record schemas validate objects with dynamic keys where all keys and values conform to specific schemas.

Basic Records

Key Schema Options

The key schema can be an enum or literal for exhaustive validation:

Implementation

The $ZodRecord type features:

1. Object validation: Checks input is a plain object and handles enumerable keys, including Symbol keys packages/zod/src/v4/core/tests/record-constructor.test.ts101-106
2. Key iteration: Iterates through Object.keys() and Object.getOwnPropertySymbols(), skipping non-enumerable properties packages/zod/src/v4/core/tests/record-constructor.test.ts69-86
3. Exhaustiveness: If the key schema is exhaustive (like z.enum), Zod ensures all required keys are present in the input packages/zod/src/v4/classic/tests/record.test.ts35-77
4. Constructor safety: Records are designed to safely handle the constructor field in objects packages/zod/src/v4/core/tests/record-constructor.test.ts4-36

Sources: packages/zod/src/v4/classic/tests/record.test.ts1-186 packages/zod/src/v4/core/tests/record-constructor.test.ts1-125 packages/docs/content/api.mdx1312-1360

---

Collection Type Hierarchy

Sources: packages/docs/content/api.mdx1152-1360 packages/zod/src/v4/classic/tests/tuple.test.ts26-39

---

Validation Pipeline

All collection schemas follow a common validation pattern with variations for their specific data structures.

Sources: packages/zod/src/v4/classic/tests/tuple.test.ts4-53 packages/zod/src/v4/classic/tests/record.test.ts47-77

---

JSON Schema Conversion

Zod supports native JSON Schema conversion via z.toJSONSchema().

Zod Type	JSON Schema Mapping	Supported
z.array()	type: "array"	✅
z.tuple()	type: "array", prefixItems	✅
z.record()	type: "object", additionalProperties	✅
z.set()	N/A	❌
z.map()	N/A	❌

Unrepresentable types like z.set() and z.map() will throw an error by default during conversion unless the unrepresentable parameter is set to "any" packages/docs/content/json-schema.mdx60-74 packages/docs/content/json-schema.mdx210-235

Sources: packages/docs/content/json-schema.mdx1-129 packages/zod/src/v4/core/tests/record-constructor.test.ts120-125

---

Path Tracking in Collections

Each collection type uses specific path formats for reporting issues.

Collection	Path Format	Example Path
Array	[index]	[0], [1]
Tuple	[index]	[0], [1] packages/zod/src/v4/classic/tests/tuple.test.ts18-20
Set	[iterationIndex]	[0], [1]
Map Key	[iterationIndex, "key"]	[0, "key"]
Map Value	[iterationIndex, "value"]	[0, "value"]
Record	[keyName]	["Salmon"] packages/zod/src/v4/classic/tests/record.test.ts68-70

Sources: packages/zod/src/v4/classic/tests/tuple.test.ts11-24 packages/zod/src/v4/classic/tests/record.test.ts62-76