zod-v4

Zod v4 Guidelines

Type Inference

Every schema MUST have inferred type above it:

export type User = z.infer<typeof User>
export const User = z.object({...})

Requirements:

• ALWAYS place type above schema
• ALWAYS use same name for type & schema
• NEVER use "Schema" suffix
• ALWAYS use JSDoc (/** */), never //
• NO EXCEPTIONS - even for internal/helper schemas

String Validation

String validations are standalone functions:

// WRONG: z.string().email()
// RIGHT: z.email(), z.url(), z.uuid(), z.ip()

Error Messages

Use error param sparingly - Zod's defaults are excellent:

// WRONG: z.email({error: "Invalid email"}) // Redundant!
// RIGHT: z.email() // Zod says "Invalid email"
// RIGHT: Only for business logic:
z.string().refine((val) => /[A-Z]/.test(val), {
  error: 'Must contain uppercase',
})

Number Types

• Use z.number() for general numbers
• z.int() for integers only (not z.number().int())
• z.int32(), z.float64() for specific types
• Numbers finite by default

Object Types

• z.object() - strips unknowns (default)
• z.strictObject() - rejects extras
• z.looseObject() - allows extras

Custom Validation

Use .check() for advanced validation, .refine() for simple validation:

Migration steps:

• .superRefine() → .check() for advanced validation with multiple issues
• In .check(): val → ctx.value, ctx.addIssue() → ctx.issues.push()
• z.ZodIssueCode.custom → 'custom' string
• Add input: ctx.value to issue object
• Use .refine() for simple boolean validation with single error

Error Formatting

• z.prettifyError() - Human-readable format
• z.treeifyError() - Tree structure format

Functions

Define function schemas with input/output types:

z.function({
  input: [z.string()],
  output: z.number(),
})

Records

z.record(keyType, valueType)

ISO Formats

• z.iso.datetime() - ISO 8601 datetime
• z.iso.date() - ISO 8601 date