api-contracts-and-zod-validation

---
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:

```bash
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

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

### For Server Actions

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

### For Forms

1. Define form fields as TypeScript interface
2. Generate Zod schema with field validators
3. Integrate with form library (React Hook Form recommended)
4. 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)

## Common Use Cases

Common patterns for applications:

- **Entity creation forms**: Validate character, location, or data entry forms
- **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 your data models.