Zod

Zod has a vast ecosystem of tools that extend its functionality. These tools are categorized by how they interact with Zod schemas:

API Libraries

Tools for building type-safe APIs and servers, such as tRPC, zodios, express-zod-api, and oRPC.

Form Integrations

Libraries that connect Zod schemas to UI form state management, including react-hook-form (via resolvers), TanStack Form, conform, and sveltekit-superforms.

Schema Transformations

• Zod to X: Convert Zod schemas into other formats like TypeScript definitions (zod-to-ts), JSON Schemas (zod-to-json-schema), or OpenAPI documentation (zod-to-openapi).
• X to Zod: Generate Zod schemas from existing definitions like TypeScript (ts-to-zod), JSON Schemas (json-schema-to-zod), or database schemas like Prisma (zod-prisma).

Mocking and Testing

Generate mock data or test fixtures from your schemas using tools like @anatine/zod-mock, zod-fixture, or zocker.

Utilities

General purpose helpers such as zod-playground for testing schemas or zod-dev for conditionally disabling runtime parsing in production.

The optout signal (value: "optional" or undefined) determines if a schema's output can be undefined even when the input was present. If optout is set to "optional", parent containers like $ZodObject or $ZodTuple may treat an undefined output as 'absent' (e.g., omitting the key from the final object or trimming a trailing tuple slot).

Schemas that set optout to "optional":

• $ZodOptional
• $ZodExactOptional

The Four Combinations of Optionality

Because optin and optout are independent, you can encounter these patterns:

• Input-required, Output-required: Standard behavior.
• Input-required, Output-optional: e.g., z.string().nullable() (if the logic allows).
• Input-optional, Output-required: e.g., z.string().default("d") (accepts absence, but always produces a value).
• Input-optional, Output-optional: e.g., z.string().optional().

In Zod v4, schemas handle missing or undefined input through a distinction between static types and runtime behavior. This is known as the "flexible inputs, strict outputs" pattern.

Core Mental Model

• Static Types are Strict: z.input<typeof schema> will show a field as required if the schema uses .catch(), .preprocess(), or .transform(). This tells TypeScript users they should provide the value.
• Runtime is Flexible: At runtime, these same schemas may accept undefined to trigger recovery logic (like .catch()) or transformation functions.
• The optin Flag: A schema's optin property determines if an object or tuple parser will allow a key to be missing. If optin is undefined, the parser rejects absent keys.
• The fallback Flag: When a schema (like .catch() or .transform()) produces a value in response to undefined, it marks that value with a fallback flag. This allows an outer .optional() wrapper to decide whether to keep that value or override it with undefined.

Summary of Schema Behaviors

// Static type says required, but runtime accepts undefined
const schema = z.string().catch("fallback");

type Input = z.input<typeof schema>; // { a: string }

// Runtime behavior
schema.parse(undefined); // returns "fallback"

TypeScript is structural, meaning types with the same shape are considered identical. To simulate nominal typing (where types are distinct even if they have the same shape), use .brand<T>(). This attaches a unique brand to the inferred type, preventing accidental assignments between structurally identical but logically different types.

Key behaviors:

• Branded types are a static-only construct; they do not affect the runtime result of .parse.
• You must parse data through the schema to obtain the branded type.
• By default, only the output type is branded. You can customize the branding direction using a second generic parameter (requires Zod 4.2+).

Branding directions:

• out (default): Only the output type is branded.
• in: Only the input type is branded.
• inout: Both input and output types are branded.

const Cat = z.object({ name: z.string() }).brand<"Cat">();
const Dog = z.object({ name: z.string() }).brand<"Dog">();

type Cat = z.infer<typeof Cat>; // { name: string } & z.$brand<"Cat">
type Dog = z.infer<typeof Dog>; // { name: string } & z.$brand<"Dog">

const pluto = Dog.parse({ name: "pluto" });
const simba: Cat = pluto; // ❌ not allowed

// Customizing branding direction (Zod 4.2+)
// output is branded (default)
z.string().brand<"Cat", "out">(); 
// input is branded
z.string().brand<"Cat", "in">(); 
// both are branded
z.string().brand<"Cat", "inout">(); 

The optin signal (value: "optional" or undefined) tells parent containers like $ZodObject or $ZodTuple whether they are allowed to omit a slot/key when the input is absent.

Schema Behavior for optin

Static/Runtime Divergence Note

For schemas like z.catch() or z.transform(), the static type (what TypeScript sees) may indicate the field is required, but the runtime parser will accept the field being missing. This allows the schema to recover or transform even when the input is undefined.

Introduced in zod@4.1, Codecs are special schemas that define a bidirectional transformation between two different types. While most Zod schemas have identical input and output types, codecs allow you to define how to move from an Input type to an Output type (decoding) and back again (encoding).

This is highly useful for network boundaries, allowing you to share a single schema between a client and server to convert between network-friendly formats (like JSON strings) and rich JavaScript objects (like Date objects).

const stringToDate = z.codec(
  z.iso.datetime(),  // input schema: ISO date string
  z.date(),          // output schema: Date object
  {
    decode: (isoString) => new Date(isoString), // ISO string → Date
    encode: (date) => date.toISOString(),       // Date → ISO string
  }
);

// Usage:
stringToDate.decode("2024-01-15T10:30:00.000Z"); // => Date
stringToDate.encode(new Date("2024-01-15T10:30:00.000Z")); // => string