What is api-contracts-and-zod-validation?

This Claude skill streamlines web development by automatically generating Zod schemas and TypeScript types for robust runtime validation. It ensures end-to-end type safety across API routes, Server Actions, and forms, helping developers build secure and reliable applications while eliminating manual boilerplate and reducing runtime errors.

When should I use api-contracts-and-zod-validation?

api-contracts-and-zod-validation is useful in the following scenarios: • Automating the generation of Zod validation schemas from existing TypeScript interfaces to ensure bidirectional type compatibility. • Implementing robust form validation for React Hook Form or native forms with field-level rules, nested structures, and custom error messages. • Securing API endpoints and Next.js Server Actions by validating request payloads, query parameters, and body data at the runtime boundary. • Maintaining synchronized API contracts between client and server code to prevent type-related bugs in full-stack applications. • Using automated scripts to parse TypeScript AST and generate equivalent Zod schemas for large-scale entity migrations.

name	api-contracts-and-zod-validation
description	Generate Zod schemas and TypeScript types for forms, API routes, and Server Actions with runtime validation. Use this skill when creating API contracts, validating request/response payloads, generating form schemas, adding input validation to Server Actions or route handlers, or ensuring type safety across client-server boundaries. Trigger terms include zod, schema, validation, API contract, form validation, type inference, runtime validation, parse, safeParse, input validation, request validation, Server Action validation.

API Contracts and Zod Validation

Generate Zod schemas with TypeScript type inference for forms, API routes, and Server Actions. Validate inputs in Server Actions or route handlers with runtime type checking.

Core Capabilities

1. Generate Zod Schemas from TypeScript Types

When creating API contracts or form validations:

Analyze existing TypeScript interfaces or types
Generate equivalent Zod schemas with proper validation rules
Ensure bidirectional type compatibility (Zod -> TypeScript)
Use z.infer<typeof schema> for automatic type inference

2. Form Validation Schemas

To create form validation with Zod:

Generate schemas for React Hook Form, Formik, or native forms
Include field-level validation rules (min/max length, regex, custom validators)
Support nested objects, arrays, and complex data structures
Provide helpful error messages for validation failures
Use references/zod_patterns.md for common validation patterns

3. API Route and Server Action Validation

To add validation to API endpoints or Server Actions:

Wrap handler logic with schema validation using .parse() or .safeParse()
Return typed errors for validation failures
Generate request/response schemas for API contracts
Validate query parameters, body payloads, and route parameters
Ensure type safety between client and server code

4. Schema Generation Script

Use scripts/generate_zod_schema.py to automate schema generation:

python scripts/generate_zod_schema.py --input types/entities.ts --output schemas/entities.ts

The script:

Parses TypeScript interfaces/types
Generates Zod schemas with appropriate validators
Preserves JSDoc comments as descriptions
Handles common patterns (optional fields, unions, enums)

Resource Files

scripts/generate_zod_schema.py

Automated TypeScript-to-Zod schema generator. Parses TypeScript AST and generates equivalent Zod schemas.

references/zod_patterns.md

Common Zod validation patterns including:

String validation (email, URL, UUID, custom regex)
Number constraints (min, max, positive, integer)
Date validation and transformation
Array and tuple validation
Object shape validation
Union and discriminated unions
Optional and nullable fields
Custom refinements and transforms
Error message customization

assets/schema_templates/

Pre-built Zod schema templates:

form_schema_template.ts - Basic form validation
api_route_schema_template.ts - API route request/response
server_action_schema_template.ts - Server Action input/output
entity_schema_template.ts - Database entity validation

Usage Workflow

For New API Routes

Define request/response TypeScript types
Generate Zod schemas using scripts/generate_zod_schema.py or templates
Add validation middleware to route handler
Return typed validation errors on failure

For Server Actions

Define input parameters as TypeScript types
Create Zod schema for validation
Use .safeParse() at the beginning of the action
Return validation errors in action result
Handle errors on the client side

For Forms

Define form fields as TypeScript interface
Generate Zod schema with field validators
Integrate with form library (React Hook Form recommended)
Display validation errors inline

Best Practices

Always use .safeParse() instead of .parse() to avoid throwing exceptions
Provide clear, user-friendly error messages
Validate early (at API boundary or Server Action entry)
Keep schemas colocated with routes/actions for maintainability
Use z.infer<typeof schema> for automatic TypeScript types
Document validation rules in schema comments
Test edge cases (empty values, invalid formats, boundary conditions)

Integration with Worldbuilding App

Common use cases for worldbuilding applications:

Entity creation forms: Validate character, location, faction data
Relationship APIs: Ensure valid entity IDs and relationship types
Timeline events: Validate dates, ordering, and event data
Search/filter endpoints: Validate query parameters and filters
Bulk operations: Validate arrays of entities or updates
Import/export: Validate file formats and data structure

Consult references/zod_patterns.md for specific validation patterns applicable to worldbuilding entities.

api-contracts-and-zod-validation

When & Why to Use This Skill

Use Cases