klh-zod-validation

Zod Validation Skill

Part of klh/skills — personal agent skills by Klaus L. Hougesen. Install: npx skills add klh/skills --skill klh-zod-validation

Overview

Zod schema validation patterns for type-safe data validation, plus deriving machine-readable contracts (JSON Schema, OpenAPI, Postman) from the same schemas — one source of truth.

This skill covers Zod schema validation for type-safe data validation. Contract derivation lives in references/openapi.md.

When to Use

Use this skill when:

• Validating API request bodies
• Parsing environment variables
• Transforming data
• Creating type-safe schemas
• Deriving JSON Schema from schemas (config, docs, tooling)
• Publishing an OpenAPI document or Postman collection from schemas

Core Principle

VALIDATE AT BOUNDARIES - Validate all external input. Trust internal data. Use Zod for type inference.

Installation

npm install zod

Basic Schemas

import { z } from "zod";

// Primitives
const stringSchema = z.string();
const numberSchema = z.number();
const booleanSchema = z.boolean();
const dateSchema = z.date();

// String validations
const emailSchema = z.string().email();
const urlSchema = z.string().url();
const uuidSchema = z.string().uuid();
const minLengthSchema = z.string().min(1).max(100);
const regexSchema = z.string().regex(/^[a-z]+$/);

// Number validations
const positiveSchema = z.number().positive();
const intSchema = z.number().int();
const rangeSchema = z.number().min(0).max(100);

// Optional and nullable
const optionalSchema = z.string().optional(); // string | undefined
const nullableSchema = z.string().nullable(); // string | null
const nullishSchema = z.string().nullish(); // string | null | undefined

Object Schemas

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  age: z.number().int().positive().optional(),
  role: z.enum(["USER", "ADMIN", "MODERATOR"]),
  createdAt: z.date(),
});

// Type inference
type User = z.infer<typeof UserSchema>;

// Partial (all fields optional)
const PartialUserSchema = UserSchema.partial();

// Pick specific fields
const UserEmailSchema = UserSchema.pick({ email: true, name: true });

// Omit fields
const UserWithoutIdSchema = UserSchema.omit({ id: true, createdAt: true });

// Extend schema
const UserWithProfileSchema = UserSchema.extend({
  profile: z.object({
    bio: z.string().optional(),
    avatar: z.string().url().optional(),
  }),
});