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.

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.

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