Zod v4 con TypeScript: validación de esquemas en APIs REST desde cero — Karen Borrero

¿Hablamos?

Cuéntame tu proyecto y te respondo en menos de 24h.

Zod v4 con TypeScript: validación de esquemas en APIs REST desde cero — Karen Borrero

Instalación y primer esquema Zod#

Instala Zod con npm. Ocupa poco espacio — 14KB minificado, sin dependencias externas, funciona en Node.js y navegadores.

Crea tu primer esquema. No es una clase complicada, es una declaración simple y legible.

TypeScript

// npm install zod
import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email('Debes proporcionar un email válido'),
  password: z.string().min(8, 'La contraseña debe tener mínimo 8 caracteres'),
  name: z.string().min(1, 'El nombre es requerido'),
});

// Zod genera tipos TypeScript automáticamente
type CreateUserInput = z.infer<typeof CreateUserSchema>;
// Equivale a: { email: string; password: string; name: string; }

const result = CreateUserSchema.parse({
  email: 'karen@karenborrero.dev',
  password: 'SecurePass123!',
  name: 'Karen',
});
// result tiene tipo CreateUserInput — autocompletar perfecto en tu IDE

Esquemas avanzados: nesting, arrays, condicionales#

Zod soporta esquemas complejos sin escribir funciones extras. Puedes anidar objetos, validar arrays, agregar lógica condicional — todo declarativo.

Ejemplo real: crear un producto con variantes anidadas. Cada variante tiene color, tamaño y stock.

TypeScript

const VariantSchema = z.object({
  color: z.enum(['rojo', 'azul', 'verde', 'negro']),
  size: z.enum(['XS', 'S', 'M', 'L', 'XL']),
  stock: z.number().int().positive('Stock debe ser mayor a 0'),
  sku: z.string().min(1),
});

const CreateProductSchema = z.object({
  title: z.string().min(3, 'Mínimo 3 caracteres'),
  description: z.string().min(10, 'Describe el producto bien'),
  price: z.number().min(0.01, 'Precio debe ser > 0'),
  variants: z.array(VariantSchema).min(1, 'Al menos 1 variante'),
  // Validación condicional: si price > 100, requiere descripción más larga
}).superRefine((data, ctx) => {
  if (data.price > 100 && data.description.length < 50) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      path: ['description'],
      message: 'Para productos > $100 necesitas descripción >= 50 caracteres',
    });
  }
  // Verificar que SKU sea único entre variantes
  const skus = data.variants.map(v => v.sku);
  if (new Set(skus).size !== skus.length) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      path: ['variants'],
      message: 'Los SKU deben ser únicos entre variantes',
    });
  }
});

type CreateProductInput = z.infer<typeof CreateProductSchema>;

Manejo de errores: ZodError y formateo amigable#

Cuando .parse() falla, lanza ZodError. Contiene todos los detalles: qué campo falló, por qué, en qué posición del array (si es nested).

Debes capturar el error y convertirlo a algo que tu cliente HTTP entienda — típicamente JSON estructurado.

TypeScript

import { ZodError } from 'zod';

function formatZodError(error: ZodError) {
  return error.errors.map(err => ({
    field: err.path.join('.'),  // ej: 'variants.0.stock' si es nested
    message: err.message,
    code: err.code,  // ej: 'too_small', 'invalid_enum_value'
    received: err.received,  // qué recibimos
  }));
}

// Uso en un endpoint Express
app.post('/products', (req, res) => {
  try {
    const data = CreateProductSchema.parse(req.body);
    // data es 100% type-safe CreateProductInput
    const newProduct = saveProduct(data);
    res.json({ success: true, product: newProduct });
  } catch (error) {
    if (error instanceof ZodError) {
      // Error de validación — devuelve errores estructurados al cliente
      return res.status(400).json({
        success: false,
        message: 'Validation failed',
        errors: formatZodError(error),
      });
    }
    // Otros errores
    res.status(500).json({ success: false, message: 'Internal error' });
  }
});

Integración en una API REST real: Express + Zod#

Integrar Zod en un endpoint Express es muy directo. Aquí un ejemplo completo y funcional que puedes copiar a tu proyecto ahora mismo.

Este código: valida request body con Zod, maneja errores de validación, devuelve respuesta estructurada, y todo con tipos TypeScript completos de principio a fin.

TypeScript

import express, { Request, Response } from 'express';
import { z, ZodError } from 'zod';

const app = express();
app.use(express.json());

// 1. Define esquema
const CreateUserSchema = z.object({
  email: z.string().email('Email inválido'),
  password: z.string().min(8, 'Mínimo 8 caracteres'),
  name: z.string().min(1, 'Nombre requerido'),
  age: z.number().int().min(18, 'Debes ser mayor de 18').optional(),
});
type CreateUserInput = z.infer<typeof CreateUserSchema>;

// 2. Middleware reutilizable para validación
function validateBody<T>(schema: z.ZodSchema<T>) {
  return (req: Request, res: Response, next: Function) => {
    try {
      req.body = schema.parse(req.body);
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        return res.status(400).json({
          success: false,
          errors: error.errors.map(e => ({
            field: e.path.join('.'),
            message: e.message,
          })),
        });
      }
      res.status(500).json({ success: false });
    }
  };
}

// 3. Usa en tu endpoint
app.post('/users', validateBody(CreateUserSchema), (req: Request, res: Response) => {
  const user: CreateUserInput = req.body;  // Type-safe
  console.log(`Crear usuario: ${user.email}`);
  res.json({ success: true, user });
});

app.listen(3000, () => console.log('API en :3000'));

Transformación de datos: .transform() y .pipe()#

A veces necesitas modificar datos después de validación. Ejemplo: convertir email a minúsculas, trimming de strings, cálculos, etc.

Zod ofrece .transform() para esto — modifica el dato DESPUÉS de validación exitosa.

TypeScript

const UserSchema = z.object({
  email: z.string().email().transform(e => e.toLowerCase()),
  name: z.string().trim(),  // Elimina espacios al inicio/final
  age: z.string().transform(Number).pipe(z.number().min(0)),
  role: z.enum(['admin', 'user']).transform(r => r.toUpperCase()),
});

const result = UserSchema.parse({
  email: '  KAREN@EXAMPLE.COM  ',
  name: '  Karen  ',
  age: '25',
  role: 'admin',
});

// result.email === 'karen@example.com' (lowercase, trim)
// result.name === 'Karen' (trimmed)
// result.age === 25 (número)
// result.role === 'ADMIN' (uppercase)