diegosouzapw 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>
- Define: Create
src/contracts/<domain>.contract.ts. - Schema: Write Zod schema for Request, Response, and Errors.
- 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