zod-schemas - SKILL.md Agent Skill

name: zod-schemas description: Zod schema validation patterns for API types

Zod Schema Validation

Define types in state-manager/types.ts using Zod schemas for runtime validation.

Structure

Define Zod schemas first, then infer TypeScript types
Use enums for tag types
Export both schemas and inferred types

// ✅ GOOD - state-manager/types.ts
import { z } from "zod";

// 1. Define tag types as enum
export enum MyDataTags {
  Items = "Items",
  Item = "Item",
}

// 2. Define Zod schemas with validation rules
const ItemSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1),
  value: z.number().min(0),
  status: z.enum(["active", "inactive"]),
  createdAt: z.string().datetime(),
});

const ItemResponseSchema = z.object({
  data: ItemSchema,
  meta: z.object({
    timestamp: z.string(),
    version: z.string(),
  }),
});

const ItemListResponseSchema = z.object({
  items: z.array(ItemSchema),
  pagination: z.object({
    nextCursor: z.string().optional(),
    total: z.number(),
  }),
});

// 3. Infer TypeScript types from schemas
export type Item = z.infer<typeof ItemSchema>;
export type ItemResponse = z.infer<typeof ItemResponseSchema>;
export type ItemListResponse = z.infer<typeof ItemListResponseSchema>;

// 4. Define query params as interfaces
export interface GetItemsParams {
  search?: string;
  limit?: number;
  cursor?: string;
}

// 5. Export schemas for runtime validation
export { ItemSchema, ItemResponseSchema, ItemListResponseSchema };

Using Schemas in API

// state-manager/api.ts
import { ItemListResponseSchema, type ItemListResponse } from "./types";

endpoints: (build) => ({
  getItems: build.query<ItemListResponse, GetItemsParams>({
    query: (params) => ({ url: "items", params }),
    transformResponse: (response: unknown) => {
      // Runtime validation
      return ItemListResponseSchema.parse(response);
    },
  }),
}),

Best Practices

Use .min(), .max(), .uuid(), .email() for field validation
Use z.enum() for fixed string values
Use z.union() for multiple possible types
Use .optional() for nullable fields
Always infer types with z.infer<typeof Schema>