Agent skill

backend-zod

TypeScript-first schema validation library. Use for ALL input validation in TypeScript projects — API inputs, form data, environment variables, config files. Essential companion for tRPC (required), React Hook Form, and any data boundary. Choose Zod when you need runtime validation with automatic TypeScript type inference.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/backend-zod

SKILL.md

Zod (Schema Validation)

Overview

Zod is a TypeScript-first schema declaration and validation library. Define a schema once, get both runtime validation AND TypeScript types automatically via z.infer<>.

Version: Zod 4 (2025) / Zod 3.x widely used
Requirements: TypeScript ≥5.5, strict mode

Key Benefit: Single source of truth for validation and types — no drift between runtime checks and TypeScript.

When to Use This Skill

✅ Use Zod when:

  • Validating API inputs (required for tRPC)
  • Building forms with react-hook-form
  • Parsing environment variables
  • Validating config files or JSON
  • Creating DTOs between layers
  • Any data crossing trust boundaries

❌ Zod is NOT for:

  • Complex business rule validation (use domain logic)
  • Database schema definition (use Prisma schema)
  • Static type-only definitions (use interfaces)

Quick Start

Installation

bash
npm install zod

Basic Usage

typescript
import { z } from 'zod';

// Define schema
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
});

// Infer TypeScript type
type User = z.infer<typeof UserSchema>;

// Validate
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data); // typed as User
} else {
  console.log(result.error.issues);
}

Core Schema Patterns

Primitives with Validation

typescript
const EmailSchema = z.string().email('Invalid email format');
const PasswordSchema = z.string().min(8, 'Min 8 characters');
const AgeSchema = z.number().int().positive().max(150);
const UrlSchema = z.string().url();
const UuidSchema = z.string().uuid();

Object Schemas

typescript
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin', 'moderator']),
  createdAt: z.date(),
});

type User = z.infer<typeof UserSchema>;

Derive Variations

typescript
// For create (omit auto-generated fields)
const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });

// For update (all optional)
const UpdateUserSchema = CreateUserSchema.partial();

// For public response (only safe fields)
const PublicUserSchema = UserSchema.pick({ id: true, name: true });

Advanced Patterns

Discriminated Unions

Use for type-safe API responses:

typescript
const ApiResponse = z.discriminatedUnion('status', [
  z.object({ status: z.literal('success'), data: UserSchema }),
  z.object({ status: z.literal('error'), code: z.string(), message: z.string() }),
]);

type ApiResponse = z.infer<typeof ApiResponse>;
// TypeScript knows: if status === 'success', data exists

Custom Validation with Refine

typescript
const PasswordSchema = z.string()
  .min(8)
  .refine(val => /[A-Z]/.test(val), 'Must contain uppercase')
  .refine(val => /[0-9]/.test(val), 'Must contain number');

Cross-Field Validation with SuperRefine

typescript
const FormSchema = z.object({
  password: z.string(),
  confirmPassword: z.string(),
}).superRefine((data, ctx) => {
  if (data.password !== data.confirmPassword) {
    ctx.addIssue({
      code: 'custom',
      message: 'Passwords must match',
      path: ['confirmPassword'],
    });
  }
});

Transforms (Data Normalization)

typescript
// Normalize email
const NormalizedEmail = z.string()
  .email()
  .transform(s => s.toLowerCase().trim());

// Parse string to number
const StringToNumber = z.string()
  .transform(s => parseInt(s, 10))
  .pipe(z.number());

Coercion (API Query Parameters)

typescript
// GET requests receive strings — use coercion
const PaginationSchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  active: z.coerce.boolean().optional(),
});

Common Schema Recipes

Pagination Input

typescript
export const PaginationSchema = z.object({
  limit: z.number().min(1).max(100).default(10),
  cursor: z.string().uuid().optional(),
});

Date Range Filter

typescript
export const DateRangeSchema = z.object({
  from: z.coerce.date(),
  to: z.coerce.date(),
}).refine(d => d.from <= d.to, 'From must be before To');

Environment Variables

typescript
const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  PORT: z.coerce.number().default(3000),
});

export const env = EnvSchema.parse(process.env);

File Upload Metadata

typescript
const FileSchema = z.object({
  name: z.string(),
  size: z.number().max(10 * 1024 * 1024), // 10MB
  type: z.enum(['image/png', 'image/jpeg', 'application/pdf']),
});

Integration with tRPC

typescript
import { z } from 'zod';
import { publicProcedure } from '../trpc';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export const userRouter = router({
  create: publicProcedure
    .input(CreateUserSchema)  // ← Zod validates automatically
    .mutation(({ input }) => {
      // input is typed as { email: string; name: string }
    }),
});

Rules

Do ✅

  • Use z.infer<typeof Schema> to derive types
  • Use discriminated unions over regular unions for objects
  • Use .safeParse() when handling errors gracefully
  • Add descriptive error messages
  • Use .default() for optional fields with defaults
  • Keep schemas in dedicated files (/schemas/*.schema.ts)

Avoid ❌

  • Async transforms in tRPC input (not supported)
  • Using .catchall() with output schemas (inference issues)
  • Multiple Zod installations (causes type inference failures)
  • Overly complex nested refinements (hard to debug)

Parse Methods

Method Throws Returns
.parse(data) Yes T
.safeParse(data) No { success, data?, error? }
.parseAsync(data) Yes Promise<T>
.safeParseAsync(data) No Promise<{ success, data?, error? }>

Use .safeParse() in application code, .parse() in trusted contexts.

Troubleshooting

yaml
"Type inference not working":
  → Check single Zod installation: npm ls zod
  → Ensure TypeScript strict mode enabled
  → Restart TypeScript server

"Coercion not working":
  → Use z.coerce.number() not z.number() for query params
  → Check input is string before coercion

"Transform output type wrong":
  → Use .pipe() after transform for additional validation
  → Check transform return type

"Refinement errors unclear":
  → Add path parameter to ctx.addIssue()
  → Use descriptive error messages

File Structure

src/schemas/
├── user.schema.ts       # User-related schemas
├── post.schema.ts       # Post-related schemas
├── common.schema.ts     # Pagination, date ranges, etc.
└── env.schema.ts        # Environment validation

References

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results