zod-validation-patterns — Claude Code rule: setup
The zod-validation-patterns rule sets Zod 4 conventions for validating TypeScript input DTOs. Use it when you need consistent schemas, inferred types, and error handling.
MIT ★ 372 updated 2026-09-10
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-typescript@developer-kitWhat zod-validation-patterns does
The rule applies to **/*.ts files and organizes schemas under libs/shared/{domain}-dto/. It recommends one file per action and entity, named like libs/shared/{domain}-dto/src/lib/{action}-{entity}.schema.ts, with both the schema and its z.infer type exported. Schemas and types should also be exposed from src/index.ts.
It covers string cleanup and checks, email fields, required and optional values, regex constants, enums, UUIDs, and Lambda validation with .safeParse(). The Zod 4 guidance also covers two-type z.record() calls, .pipe() chains, .refine() checks, the unified error option, and the difference between .default() and .prefault(). Zod 3 code needs a review because these conventions target Zod 4.
What it helps with
- organize Zod schemas inside DTO libraries
- order string transforms before validation
- export inferred types with
z.infer - validate Lambda input with
.safeParse() - replace Zod 3 patterns with Zod 4 syntax
Example prompts for the agent
- Create a
CreateTenantSchemafor the tenant DTO, trimming the name and validatingadminEmail. - Review the schemas under
libs/shared/{domain}-dto/and align string transforms and checks with this rule. - Update any one-argument
z.record()call to the Zod 4 form with explicit key and value types.
How to install zod-validation-patterns
1Plugin marketplace
/plugin marketplace add giuseppe-trisciuoglio/developer-kit/plugin install developer-kit-typescript@developer-kit2Manually: put the files in place
.claude/rules/zod-validation-patterns.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/zod-validation-patterns.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/zod-validation-patterns.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/zod-validation-patterns.mdManually: put the files in place
.clinerules/zod-validation-patterns.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about zod-validation-patterns
How do I install zod-validation-patterns in Claude Code?
Run /plugin marketplace add giuseppe-trisciuoglio/developer-kit, then /plugin install developer-kit-typescript@developer-kit. Add the rule file at .claude/rules/zod-validation-patterns.md.
What does zod-validation-patterns do?
It defines a consistent way to structure and write Zod 4 schemas for TypeScript input DTOs. It also covers inferred types, validation errors, and Lambda handler checks.
Which Zod version does zod-validation-patterns target?
It targets Zod 4, including z.email(), z.uuid(), two-argument z.record(), the unified error option, and .prefault().
Source text
zod-validation-patterns.md · MIT
---
paths:
- "**/*.ts"
---
# Rule: Zod 4 Validation Patterns
## Context
Enforce consistent validation patterns using Zod v4 for input DTOs in `libs/shared/{domain}-dto/`. Zod schemas provide type-safe runtime validation with clean TypeScript inference.
## Guidelines
### Schema File Organization
- Place Zod schemas in `libs/shared/{domain}-dto/src/lib/{action}-{entity}.schema.ts`
- Export both the schema (`const`) and the inferred type (`type`)
- Use descriptive schema names: `{Action}{Entity}Schema` (e.g., `CreateTenantSchema`)
```typescript
// libs/shared/tenant-dto/src/lib/create-tenant.schema.ts
import { z } from 'zod';
export const CreateTenantSchema = z.object({
tenantName: z.string().trim().min(1).max(255),
adminEmail: z.string().trim().toLowerCase().pipe(z.email()),
});
export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
```
### String Validation Chain
Always apply transformations **before** validations. The correct order:
1. `.string()` — base type
2. `.trim()` — remove whitespace
3. `.toLowerCase()` / `.toUpperCase()` — normalize case if applicable
4. `.pipe()` — complex transformations (email, UUID parsing)
5. `.min()`, `.max()`, `.regex()` — validations
6. Custom error messages as last parameter
```typescript
// ✅ Correct order
z.string()
.trim()
.toLowerCase()
.pipe(z.email('Invalid email format'))
.max(254, 'Email must be at most 254 characters')
// ❌ Wrong: validations before trim
z.string().min(1).trim() // trim happens after min check
```
### Required Fields
Use `.min(1, 'message')` for required non-empty strings:
```typescript
tenantName: z
.string()
.trim()
.min(1, 'Tenant name is required')
.max(255, 'Tenant name must be at most 255 characters')
```
### Email Validation
Use `.pipe(z.email())` with trim and lowercase:
```typescript
email: z
.string()
.trim()
.toLowerCase()
.max(254, 'Email must be at most 254 characters')
.pipe(z.email('Invalid email format'))
```
### Regex Patterns
- Define regex constants at module level with descriptive names
- Use `u` flag for Unicode patterns
- Provide clear error messages showing expected format
```typescript
const SUPPORTED_VAT_REGEX = /^IT\d{11}$/u;
vatNumber: z
.string()
.trim()
.min(1, 'VAT number is required')
.max(14, 'VAT number must be IT followed by 11 digits')
.regex(SUPPORTED_VAT_REGEX, 'VAT number must be in format IT followed by 11 digits (e.g., IT12345678901)')
```
### Enum Validation with Zod
Export native TypeScript enums from `*-enum.ts` files. For Zod schemas, use `.enum()` which handles both string unions AND native enums in Zod v4:
```typescript
// tenant-status.enum.ts
export enum TenantStatus {
Created = 'created',
Active = 'active',
Suspended = 'suspended',
Deleted = 'deleted',
}
// In schema: use z.enum() for Zod-native validation with string literals
status: z.enum(['created', 'active', 'suspended', 'deleted'])
// In Zod v4, z.enum() also accepts native TypeScript enums
// z.nativeEnum() is deprecated - prefer z.enum()
import { TenantStatus } from './tenant-status.enum';
status: z.enum(TenantStatus)
```
### Type Inference
Always export the inferred type using `z.infer`:
```typescript
export const CreateTenantSchema = z.object({ /* ... */ });
export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
```
### Optional Fields
Use `.optional()` for nullable fields:
```typescript
description: z
.string()
.trim()
.max(1000)
.optional(),
```
### Barrel Export Pattern
Export schemas and types from the library index:
```typescript
// src/index.ts
export { CreateTenantSchema } from './lib/create-tenant.schema';
export type { CreateTenantInput } from './lib/create-tenant.schema';
```
### Usage in Lambda Handlers
Use `.safeParse()` for validation with error handling:
```typescript
import { CreateTenantSchema, type CreateTenantInput } from '@sibill-erp-gateway/shared/tenant-dto';
const validationResult = CreateTenantSchema.safeParse(parseResult.data);
if (!validationResult.success) {
return this.validationErrorResponse(validationResult.error.issues, requestId);
}
// validationResult.data is typed as CreateTenantInput
```
## Zod 4 Specific Patterns
### UUID Validation
Zod v4 supports one UUID validation approaches:
```typescript
// Standalone z.uuid() - RFC 9562/4122 compliant
const strictUuidSchema = z.uuid();
strictUuidSchema.parse('550e8400-e29b-41d4-a716-446655440000'); // ✅
```
Use `z.guid()` for permissive UUID-like patterns (any 8-4-4-4-12 hex format).
### Record Schemas (Zod v4 Breaking Change)
Zod v4 **requires both key and value types** explicitly - single-argument usage is removed:
```typescript
// ❌ Zod 3 (deprecated in v4)
z.string().uuid();
z.record(z.string()) // Error: Expected 2-3 arguments, got 1
// ✅ Zod 4 - both key and value types required
z.record(z.string(), z.string()) // Record<string, string>
z.record(z.string(), z.unknown()) // Record<string, unknown>
z.record(z.enum(['a', 'b']), z.number()) // Record<'a'|'b', number>
```
### .pipe() for Transformations
Zod 4 uses `.pipe()` for sequential transformations:
```typescript
// Transform and validate email
z.string()
.trim()
.toLowerCase()
.pipe(z.email()) // pipe creates new zod schema
// Custom transformation with validation
z.string()
.transform(val => val.toUpperCase())
.pipe(z.enum(['VALUE1', 'VALUE2']))
```
### Refine with Custom Validation
Use `.refine()` for business logic validation:
```typescript
vatNumber: z
.string()
.trim()
.min(1)
.refine(
(val) => validateVatChecksum(val),
{ message: 'VAT checksum validation failed' }
)
```
### Error Handling (Zod v4)
Zod v4 uses a unified `error` parameter instead of separate `invalid_type_error`/`required_error`:
```typescript
// ❌ Zod 3 style (deprecated in v4)
z.string({ invalid_type_error: 'Must be a string', required_error: 'Required' })
// ✅ Zod 4 style - unified error parameter
z.string({ error: 'Invalid string value' })
// ✅ Zod 4 with error function for dynamic messages
z.string({
error: (issue) => issue.input === undefined ? 'Required' : 'Invalid'
})
```
### Default Values (Zod v4)
`.default()` in Zod v4 short-circuits for `undefined`. Use `.prefault()` to replicate Zod 3's pre-parse default behavior:
```typescript
// .default() only applies when value is undefined
const schema = z.string().default('fallback');
schema.parse(undefined); // 'fallback'
schema.parse(null); // Error (null is not undefined)
// Use .prefault() for Zod 3-like behavior
const prefaultSchema = z.string().prefault(() => 'fallback');
```
## Examples
### ✅ Good
```typescript
export const CreateTenantSchema = z.object({
tenantName: z
.string()
.trim()
.min(1, 'Tenant name is required')
.max(255, 'Tenant name must be at most 255 characters')
.regex(/^[a-zA-Z0-9_\-\s]+$/u, 'Tenant name contains invalid characters'),
vatNumber: z
.string()
.trim()
.min(1, 'VAT number is required')
.regex(SUPPORTED_VAT_REGEX, 'Invalid VAT format'),
adminEmail: z
.string()
.trim()
.toLowerCase()
.max(254)
.pipe(z.email('Invalid email format')),
});
export type CreateTenantInput = z.infer<typeof CreateTenantSchema>;
// UUID validation
const uuidSchema = z.uuid();
const userIdSchema = z.string().uuid();
// Record with key and value types (Zod v4)
const metadataSchema = z.record(z.string(), z.string());
const payloadSchema = z.record(z.string(), z.unknown());
// Enum validation with TypeScript native enum
const statusSchema = z.enum(TenantStatus); // z.enum() handles native enums in v4
```
### ❌ Bad
```typescript
// No trim before validation — accepts " value "
z.string().min(1).max(255)
// No lowercase for email — case-sensitive comparison
z.string().email()
// Missing error messages — generic Zod errors
z.string().min(1).max(255).regex(/^[a-z]+$/)
// Missing type export
export const schema = z.object({ name: z.string() });
// No: export type SchemaInput = z.infer<typeof schema>;
// Regex without unicode flag
z.string().regex(/^[a-z]+$/) // Should be /^[a-z]+$/u
// Record with single argument (Zod v4 breaking change)
z.record(z.string()) // Error: Expected 2-3 arguments, got 1
// Native enum with z.nativeEnum() (deprecated in v4)
z.nativeEnum(MyEnum) // Use z.enum(MyEnum) instead
```
## File Naming
| Type | Naming | Example |
|---|---|---|
| Schema file | `{action}-{entity}.schema.ts` | `create-tenant.schema.ts` |
| Schema const | `{Action}{Entity}Schema` | `CreateTenantSchema` |
| Inferred type | `{Action}{Entity}Input` | `CreateTenantInput` |
| Enum file | `{entity}-status.enum.ts` | `tenant-status.enum.ts` |
| DTO file | `{entity}.dto.ts` | `tenant.dto.ts` |
© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit