zod

Q: ¿Zod en cada capa o solo en los controladores?

Valida en los límites (HTTP, entorno, cola, webhooks externos). Dentro de la lógica de dominio, confía en los valores tipados. No vuelvas a analizar el mismo objeto tres veces por solicitud.

Q: ¿Cómo evito filtrar los internos de Zod en los errores de la API?

Mapea error.flatten().fieldErrors a tu estándar de errores de API. Nunca devuelvas el stack de ZodError o issues en bruto en producción.

Q: ¿Zod vs JSON Schema para OpenAPI?

Usa Zod como fuente de verdad y genera OpenAPI con zod-to-openapi o mantén un JSON Schema paralelo para la documentación pública. Elige una fuente, no ambas editadas a mano.

Zod valida datos en los límites de la API y la configuración para que la entrada inválida nunca llegue a la lógica de negocio. Un esquema proporciona comprobaciones en tiempo de ejecución y tipos de TypeScript sin desviaciones.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import { z } from "zod";
 
export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(120),
  role: z.enum(["member", "admin"]).default("member"),
});
 
export type CreateUserInput = z.infer<typeof createUserSchema>;
 
// Ruta de Fastify
app.post("/users", async (req, reply) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return reply.status(400).send({ errors: parsed.error.flatten() });
  }
  return createUser(parsed.data);
});

Cuándo usarlo:

Cada superficie pública de cuerpo HTTP, consulta y parámetros
Validación de process.env al inicio (consulta también Validación de Zod y env-schema)
Cargas útiles de trabajos de BullMQ antes de la ejecución del manejador
Cargas útiles de firmas de webhook de Stripe, GitHub, etc.

Ejemplo de trabajo

// src/schemas/order.ts
import { z } from "zod";
 
export const orderItemSchema = z.object({
  sku: z.string().uuid(),
  quantity: z.coerce.number().int().positive(),
});
 
export const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(orderItemSchema).min(1),
  shipBy: z.string().datetime().optional(),
});
 
export type CreateOrderInput = z.infer<typeof createOrderSchema>;
 
// src/routes/orders.ts
import type { FastifyInstance } from "fastify";
import { createOrderSchema } from "../schemas/order.js";
 
export async function orderRoutes(app: FastifyInstance): Promise<void> {
  app.post("/orders", async (req, reply) => {
    const result = createOrderSchema.safeParse(req.body);
    if (!result.success) {
      req.log.warn({ validation: result.error.flatten() }, "invalid_order");
      return reply.status(400).send({
        error: "validation_failed",
        details: result.error.flatten().fieldErrors,
      });
    }
    const order = await createOrder(result.data);
    return reply.status(201).send(order);
  });
}

// src/workers/email.worker.ts
import { z } from "zod";
 
const emailJobSchema = z.object({
  to: z.string().email(),
  templateId: z.string(),
  vars: z.record(z.string()),
});
 
export async function processEmailJob(raw: unknown): Promise<void> {
  const job = emailJobSchema.parse(raw); // lanza → reintento/DLQ de BullMQ
  await sendEmail(job);
}

Comportamientos clave:

safeParse para HTTP: mapea a 400 sin lanzar excepciones
parse para workers: permite que la cola reintente los mensajes venenosos
z.coerce.number() para cadenas de consulta y variables de entorno
.refine() para reglas entre campos (por ejemplo, shipBy debe ser futuro)

Comparación

Enfoque	Pros	Contras
Zod	Inferencia de TS, componible, gran DX	Costo en tiempo de ejecución en rutas críticas (generalmente insignificante)
Solo JSON Schema	Nativo de Fastify, exportación OpenAPI	No hay tipos TS compartidos sin generación de código
Comprobaciones `if` manuales	Cero dependencias	Se desvía de los tipos; patrones no testeables
class-validator (Nest)	Ecosistema de Nest	Magia de decoradores; menos portable

Los equipos de Fastify a menudo usan Zod + @fastify/type-provider-typebox o convierten Zod a JSON Schema para la serialización de respuestas.
Los equipos de NestJS pueden usar nestjs-zod o pipes globales con DTOs de Zod.

Pruebas

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createOrderSchema } from "./order.js";
 
describe("createOrderSchema", () => {
  it("rechaza elementos vacíos", () => {
    const result = createOrderSchema.safeParse({
      customerId: "550e8400-e29b-41d4-a716-446655440000",
      items: [],
    });
    assert.equal(result.success, false);
  });
});

Prueba los esquemas directamente: más rápido que las pruebas de integración HTTP para casos extremos.
Mantén los fixtures inválidos "golden" en __fixtures__/invalid-orders.json.

Preguntas frecuentes

¿Zod en cada capa o solo en los controladores?

Valida en los límites (HTTP, entorno, cola, webhooks externos). Dentro de la lógica de dominio, confía en los valores tipados. No vuelvas a analizar el mismo objeto tres veces por solicitud.

¿Cómo evito filtrar los internos de Zod en los errores de la API?

Mapea error.flatten().fieldErrors a tu estándar de errores de API. Nunca devuelvas el stack de ZodError o issues en bruto en producción.

¿Zod vs JSON Schema para OpenAPI?

Usa Zod como fuente de verdad y genera OpenAPI con zod-to-openapi o mantén un JSON Schema paralelo para la documentación pública. Elige una fuente, no ambas editadas a mano.

Relacionado

Validación de Zod y env-schema - análisis de entorno al inicio
Validación de JSON Schema - alternativa nativa de Fastify
Estándares de respuesta de errores - forma 400
Conceptos básicos de bibliotecas esenciales - cuando Zod es el predeterminado

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Receta

Tarjeta de receta de referencia rápida: lista para copiar y pegar.

import { z } from "zod";
 
export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(120),
  role: z.enum(["member", "admin"]).default("member"),
});
 
export type CreateUserInput = z.infer<typeof createUserSchema>;
 
// Ruta de Fastify
app.post("/users", async (req, reply) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return reply.status(400).send({ errors: parsed.error.flatten() });
  }
  return createUser(parsed.data);
});

Cuándo usarlo:

Cada superficie pública de cuerpo HTTP, consulta y parámetros
Validación de process.env al inicio (consulta también Validación de Zod y env-schema)
Cargas útiles de trabajos de BullMQ antes de la ejecución del manejador
Cargas útiles de firmas de webhook de Stripe, GitHub, etc.

Ejemplo de trabajo

// src/schemas/order.ts
import { z } from "zod";
 
export const orderItemSchema = z.object({
  sku: z.string().uuid(),
  quantity: z.coerce.number().int().positive(),
});
 
export const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(orderItemSchema).min(1),
  shipBy: z.string().datetime().optional(),
});
 
export type CreateOrderInput = z.infer<typeof createOrderSchema>;
 
// src/routes/orders.ts
import type { FastifyInstance } from "fastify";
import { createOrderSchema } from "../schemas/order.js";
 
export async function orderRoutes(app: FastifyInstance): Promise<void> {
  app.post("/orders", async (req, reply) => {
    const result = createOrderSchema.safeParse(req.body);
    if (!result.success) {
      req.log.warn({ validation: result.error.flatten() }, "invalid_order");
      return reply.status(400).send({
        error: "validation_failed",
        details: result.error.flatten().fieldErrors,
      });
    }
    const order = await createOrder(result.data);
    return reply.status(201).send(order);
  });
}

// src/workers/email.worker.ts
import { z } from "zod";
 
const emailJobSchema = z.object({
  to: z.string().email(),
  templateId: z.string(),
  vars: z.record(z.string()),
});
 
export async function processEmailJob(raw: unknown): Promise<void> {
  const job = emailJobSchema.parse(raw); // lanza → reintento/DLQ de BullMQ
  await sendEmail(job);
}

Comportamientos clave:

safeParse para HTTP: mapea a 400 sin lanzar excepciones
parse para workers: permite que la cola reintente los mensajes venenosos
z.coerce.number() para cadenas de consulta y variables de entorno
.refine() para reglas entre campos (por ejemplo, shipBy debe ser futuro)

Comparación

Enfoque	Pros	Contras
Zod	Inferencia de TS, componible, gran DX	Costo en tiempo de ejecución en rutas críticas (generalmente insignificante)
Solo JSON Schema	Nativo de Fastify, exportación OpenAPI	No hay tipos TS compartidos sin generación de código
Comprobaciones `if` manuales	Cero dependencias	Se desvía de los tipos; patrones no testeables
class-validator (Nest)	Ecosistema de Nest	Magia de decoradores; menos portable

Los equipos de Fastify a menudo usan Zod + @fastify/type-provider-typebox o convierten Zod a JSON Schema para la serialización de respuestas.
Los equipos de NestJS pueden usar nestjs-zod o pipes globales con DTOs de Zod.

Pruebas

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createOrderSchema } from "./order.js";
 
describe("createOrderSchema", () => {
  it("rechaza elementos vacíos", () => {
    const result = createOrderSchema.safeParse({
      customerId: "550e8400-e29b-41d4-a716-446655440000",
      items: [],
    });
    assert.equal(result.success, false);
  });
});

Prueba los esquemas directamente: más rápido que las pruebas de integración HTTP para casos extremos.
Mantén los fixtures inválidos "golden" en __fixtures__/invalid-orders.json.

Preguntas frecuentes

¿Zod en cada capa o solo en los controladores?

Valida en los límites (HTTP, entorno, cola, webhooks externos). Dentro de la lógica de dominio, confía en los valores tipados. No vuelvas a analizar el mismo objeto tres veces por solicitud.

¿Cómo evito filtrar los internos de Zod en los errores de la API?

Mapea error.flatten().fieldErrors a tu estándar de errores de API. Nunca devuelvas el stack de ZodError o issues en bruto en producción.

¿Zod vs JSON Schema para OpenAPI?

Usa Zod como fuente de verdad y genera OpenAPI con zod-to-openapi o mantén un JSON Schema paralelo para la documentación pública. Elige una fuente, no ambas editadas a mano.

Relacionado

Validación de Zod y env-schema - análisis de entorno al inicio
Validación de JSON Schema - alternativa nativa de Fastify
Estándares de respuesta de errores - forma 400
Conceptos básicos de bibliotecas esenciales - cuando Zod es el predeterminado

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

zod

Buscar en la documentación

zod