# API Contracts And Validation

> Define and validate API contracts using Zod Use when this capability is needed.

- Skill: `tomevault-io/api-contracts-and-validation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/api-contracts-and-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-contracts-and-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/api-contracts-and-validation

---


# API Contracts & Validation Skill

## Overview

Define Zod schemas as the source of truth for API contracts and validation.

## Usage

```
/api-contracts-and-validation
```

## Documentation Reference

- Use Ref tools to confirm Zod API details and best practices when needed.

## Identity
**Role**: API Designer
**Objective**: Create single-source-of-truth definitions for API structures using Zod schemas, shared between client and server.

## Standards

### 1. Zod First
Define the schema **before** the Typescript type.
```typescript
import { z } from 'zod';

// 1. Schema
export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['ADMIN', 'USER']),
  meta: z.record(z.string()).optional()
});

// 2. Inference
export type User = z.infer<typeof UserSchema>;
```

### 2. Runtime Validation
**Server-Side**: All inputs (Req Body, Params, Query) MUST be parsed.
```typescript
app.post('/user', (req, res) => {
  const result = UserSchema.safeParse(req.body);
  if (!result.success) return res.status(400).json(result.error);
  // ...
});
```

### 3. Client-Side Safe Fetching
Validate responses from the API before using them in the UI to prevent "Undefined is not a function" crashes.

## Workflow

### Contract Creation
**Command**: `/make-contract <name>`
1.  **Define**: Create `src/contracts/<domain>.contract.ts`.
2.  **Schema**: Write Zod schema for Request, Response, and Errors.
3.  **Export**: Export inferred types.

### Code Gen (Optional)
If using tRPC or OpenAPI, update the generation scripts.

## Error Handling
- **Parse Errors**: Zod returns detailed error maps. Convert these to user-friendly messages for the frontend.
- **Strict Mode**: Schemas should use `.strict()` by default to strip unknown fields.

## Outputs

- Zod schemas and derived types for shared API contracts.

## Related Skills

- `/ts-strict-guardian` - Enforce strict TypeScript safety

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/etroxtaran) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->