Schema Validator

---
name: schema-validator
description: |
  Trigger when the user asks to validate data against a schema, add input
  validation, or build type-safe boundaries. Phrases: "validate input",
  "add zod schema", "type-safe API", "request validation", "parse JSON safely".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# Schema Validator

Add input validation at the boundaries of a system so invalid data never
reaches business logic. Zod for TypeScript, Pydantic for Python.

## Prerequisites

- Boundaries identified (HTTP routes, queue workers, webhook handlers,
  external API responses you consume)
- Validation library installed

## Steps

1. **Define the schema separately from the route handler.** Schemas are
   reusable, testable, and serve as documentation.

   ```ts
   // schemas/user.ts
   export const CreateUserSchema = z.object({
     email: z.string().email(),
     name: z.string().min(1).max(100),
     age: z.number().int().min(13).max(150).optional(),
   });
   export type CreateUser = z.infer<typeof CreateUserSchema>;
   ```

2. **Parse at the boundary.** Use `safeParse` and branch on the result:
   ```ts
   const result = CreateUserSchema.safeParse(await request.json());
   if (!result.success) {
     return Response.json({ error: result.error.format() }, { status: 422 });
   }
   const user = result.data; // fully typed, validated
   ```

3. **Validate external API responses too.** Third-party APIs break their
   schemas without notice. If you depend on a response shape, validate it
   at the boundary rather than trusting it deep in your code.

4. **Validate env vars at startup.** See env-config-manager skill. Missing
   env vars should kill the app on boot, not silently return undefined at
   request time.

5. **Share schemas between client and server.** A zod schema in a shared
   package lets the client validate the same way the server does, before
   the request goes out. Saves a round trip on bad input.

6. **Keep schemas small and composable.** If a schema exceeds ~50 lines,
   break it into sub-schemas. Composition reads better and reuses.

## Common mistakes

- Parsing without a schema using `as Type` casts. Type assertions are not
  validation.
- Using `z.any()` to silence a type error. That defeats the point.
- Not validating response headers when they matter (content-type, rate
  limit).
- Schema too loose, lets through obviously invalid data.
- Schema too strict, breaks on minor valid variations.

## Output

- Schema module(s) defined separately from handlers
- All boundaries parse incoming data
- Type inference flows from schema through to handler logic
- Test suite covers the "invalid input returns 422" path