Dynamic string-keyed maps
Validate caches, lookup tables, or stores indexed by arbitrary string IDs.
Zod · Function
z.record
Creates a schema for dictionary-like objects with dynamic keys. It validates each key with one schema and each value with another, producing a corresponding TypeScript Record type.
How it works
z.record(keySchema, valueSchema) creates a schema for an object with dynamically named keys. Each key is checked against the key schema and each corresponding value against the value schema; the inferred TypeScript type is a Record with those key and value types.
Syntax
z.record(keySchema, valueSchema)Parameters
| Name | Type | Description |
|---|---|---|
keySchema | Zod schema | Schema applied to each property key; it must be assignable to string | number | symbol. |
valueSchema | Zod schema | Schema applied to each property value. |
Returns
A Zod record schema whose inferred output has the shape Record<Key, Value>.
Key points
- Use records for dictionary-shaped objects whose property names and values follow consistent schemas.
- Keys may use schemas compatible with string, number, or symbol property-key types.
- Numeric-key records are supported in a manner designed to align with TypeScript's record behavior.
Common mistakes
- Unexpected keys are rejected by default; use
z.looseRecord()when non-matching keys should pass through unchanged. - Numeric record keys are represented as object-property strings and are checked as numeric strings.
Example: Validate a keyed object
import { z } from "zod";
const UserStore = z.record(z.string(), z.object({ name: z.string() }));
const result = UserStore.parse({
alice: { name: "Alice" },
bob: { name: "Bob" },
});
console.log(result.alice.name);This validates an object whose keys are strings and whose values are objects containing a string name.
When to use it
Validated value dictionaries
Require a consistent structure for every value in a keyed collection.
Exhaustive enum-keyed records
Represent a finite, exhaustive set of named entries with an enum key schema.
Interview questions
QWhat does z.record validate?
z.record(keySchema, valueSchema) validates a dictionary-like object with dynamic keys. The key schema must be assignable to string | number | symbol, while the value schema validates every property value.
Follow-up: How would you model a finite set of required keys? Use an enum as the key schema; current Zod checks exhaustiveness and requires all enum keys during parsing.
QWhat is the inferred type of a string-to-number record?
For z.record(z.string(), z.number()), each property key must satisfy the string key schema and each property value must be a number. Its inferred type corresponds to Record<string, number>.
Follow-up: What happens with an invalid key? The default record schema reports an error; z.looseRecord instead preserves keys that do not match.
QHow does the current API differ from the older one-argument form?
The current signature takes two schemas: one for keys and one for values. The older single-argument form is no longer supported in the current major version.
Follow-up: Can the key schema be numeric? Yes; Zod validates an object key as a valid numeric string when a number schema is used.
Related
z.looseRecordz.objectz.enumz.infer