Zod Validation Utilities Overview Production-ready Zod v4 patterns for reusable, type-safe validation with minimal boilerplate. Focuses on modern APIs, predictable error handling, and form integration. When to Use Defining request/response validation schemas in TypeScript services Parsing untrusted input from APIs, forms, env vars, or external systems Standardizing coercion, transforms, and cross-field validation Building reusable schema utilities across teams Integrating React Hook Form with Zod using zodResolver Instructions Start with strict object schemas and explicit field constraints Prefer modern Zod v4 APIs and the error option for error messages Use coercion at boundaries ( z.coerce.* ) when input types are uncertain Keep business invariants in refine / superRefine close to schema definitions Export both schema and inferred types ( z.input / z.output ) for consistency Reuse utility schemas (email, id, dates, pagination) to reduce duplication Examples 1) Modern Zod 4 primitives and object errors import { z } from "zod" ; export const UserIdSchema = z . uuid ( { error : "Invalid user id" } ) ; export const EmailSchema = z . email ( { error : "Invalid email" } ) ; export const WebsiteSchema = z . url ( { error : "Invalid URL" } ) ; export const UserProfileSchema = z . object ( { id : UserIdSchema , email : EmailSchema , website : WebsiteSchema . optional ( ) , } , { error : "Invalid user profile payload" } ) ; 2) Coercion, preprocess, and transform import { z } from "zod" ; export const PaginationQuerySchema = z . object ( { page : z . coerce . number ( ) . int ( ) . min ( 1 ) . default ( 1 ) , pageSize : z . coerce . number ( ) . int ( ) . min ( 1 ) . max ( 100 ) . default ( 20 ) , includeArchived : z . coerce . boolean ( ) . default ( false ) , } ) ; export const DateFromUnknownSchema = z . preprocess ( ( value ) => ( typeof value === "string" || value instanceof Date ? value : undefined ) , z . coerce . date ( { error : "Invalid date" } ) ) ; export const NormalizedEmailSchema = z . string ( ) . trim ( ) . toLowerCase ( ) . email ( { error : "Invalid email" } ) . transform ( ( value ) => value as Lowercase < string
) ; 3) Complex schema structures import { z } from "zod" ; const TagSchema = z . string ( ) . trim ( ) . min ( 1 ) . max ( 40 ) ; export const ProductSchema = z . object ( { sku : z . string ( ) . min ( 3 ) . max ( 24 ) , tags : z . array ( TagSchema ) . max ( 15 ) , attributes : z . record ( z . string ( ) , z . union ( [ z . string ( ) , z . number ( ) , z . boolean ( ) ] ) ) , dimensions : z . tuple ( [ z . number ( ) . positive ( ) , z . number ( ) . positive ( ) , z . number ( ) . positive ( ) ] ) , } ) ; export const PaymentMethodSchema = z . discriminatedUnion ( "type" , [ z . object ( { type : z . literal ( "card" ) , last4 : z . string ( ) . regex ( / ^ \d {4} $ / ) } ) , z . object ( { type : z . literal ( "paypal" ) , email : z . email ( ) } ) , z . object ( { type : z . literal ( "wire" ) , iban : z . string ( ) . min ( 10 ) } ) , ] ) ; 4) refine and superRefine import { z } from "zod" ; export const PasswordSchema = z . string ( ) . min ( 12 ) . refine ( ( v ) => / [ A - Z ] / . test ( v ) , { error : "Must include an uppercase letter" } ) . refine ( ( v ) => / \d / . test ( v ) , { error : "Must include a number" } ) ; export const RegisterSchema = z . object ( { email : z . email ( ) , password : PasswordSchema , confirmPassword : z . string ( ) , } ) . superRefine ( ( data , ctx ) => { if ( data . password !== data . confirmPassword ) { ctx . addIssue ( { code : "custom" , path : [ "confirmPassword" ] , message : "Passwords do not match" , } ) ; } } ) ; 5) Optional, nullable, nullish, and default import { z } from "zod" ; export const UserPreferencesSchema = z . object ( { nickname : z . string ( ) . min ( 2 ) . optional ( ) , // undefined allowed bio : z . string ( ) . max ( 280 ) . nullable ( ) , // null allowed avatarUrl : z . url ( ) . nullish ( ) , // null or undefined allowed locale : z . string ( ) . default ( "en" ) , // fallback when missing } ) ; 6) React Hook Form integration ( zodResolver ) import { useForm } from "react-hook-form" ; import { zodResolver } from "@hookform/resolvers/zod" ; import { z } from "zod" ; const ProfileFormSchema = z . object ( { name : z . string ( ) . min ( 2 , { error : "Name too short" } ) , email : z . email ( { error : "Invalid email" } ) , age : z . coerce . number ( ) . int ( ) . min ( 18 ) , } ) ; type ProfileFormInput = z . input < typeof ProfileFormSchema
; type ProfileFormOutput = z . output < typeof ProfileFormSchema
; const form = useForm < ProfileFormInput , unknown , ProfileFormOutput
( { resolver : zodResolver ( ProfileFormSchema ) , criteriaMode : "all" , } ) ; Best Practices Keep schemas near boundaries (HTTP handlers, queues, config loaders) Prefer safeParse for recoverable flows; parse for fail-fast execution Share small schema utilities ( id , email , slug ) to enforce consistency Use z.input and z.output when transforms/coercions change runtime shape Avoid overusing preprocess ; prefer explicit z.coerce.* where possible Treat external payloads as untrusted and always validate before use Constraints and Warnings Ensure examples match your installed zod major version (v4 APIs shown) error is the preferred option for custom errors in Zod v4 patterns Discriminated unions require a stable discriminator key across variants Coercion can hide bad upstream data; add bounds and refinements defensively