designing-zod-schemas

Zod schemas provide runtime validation while inferring TypeScript types automatically. Define a schema, use z.infer to extract its type, and validate incoming data with safeParse to catch errors at runtime while maintaining type consistency across your application.

Zod discriminated unions let you define schemas where a specific field determines the structure of the rest. Use z.discriminatedUnion to create type-safe validators for tagged data, ensuring only valid shape combinations pass validation while TypeScript narrows types correctly.

Zod transforms and refinements let you modify or validate data during parsing. Use .transform to reshape values and .refine or .superRefine to add custom validation logic, enabling complex validation workflows within a single schema without separate processing steps.

In a Zod-first workflow, define your schema once, then extract TypeScript types with z.infer. The same schema validates runtime data and generates types, eliminating duplication and ensuring validation rules and type definitions stay synchronized throughout your codebase.

Create test data builders using your schemas and use safeParse in tests to verify validation passes and fails as expected. This pattern documents validation constraints, catches regressions, and ensures schema behavior matches your domain requirements.

Branded types add semantic meaning to primitives at compile time, preventing invalid values from entering your domain model. Zod supports branded types through refinements, letting you encode constraints like valid email formats or positive numbers directly in your type system.