Saltar al contenido

Validación con zod en TypeScript: revisa los datos una vez, en la entrada

En la práctica/ 13 min de lectura

Un esquema de zod para el formulario, la ruta de API y el tipo: safeParse, un 400 con errores por campo, z.infer y mensajes que se entienden. Probado con zod 4.6.7.

  • JavaScript
  • Next.js
  • Seguridad
En este artículo (9)
  1. Validación con zod: revisar una sola vez, en la entrada
  2. Definir el esquema
  3. Usarlo en el formulario
  4. Usarlo en la API: rechazar con 400
  5. z.infer para el tipo
  6. Errores útiles para el usuario
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

La validación con zod se hace una sola vez, donde los datos entran a tu código: en el formulario antes de enviar y en la ruta de API antes de guardar. Defines un esquema con z.object, lo revisas con safeParse, respondes 400 si falla y sacas el tipo de TypeScript con z.infer.

Aquí tienes el ejemplo completo con zod 4.6.7, la versión actual en npm al 19 de noviembre de 2026: el esquema de un pedido, la función que revisa el formulario, el componente y la ruta de API de Next.js que rechaza con 400. Lo corrimos en Node 22 y lo revisamos con tsc --strict.

Validación con zod: revisar una sola vez, en la entrada

Los datos que llegan de fuera no son del tipo que dice tu código. Un formulario manda texto. Un fetch manda lo que quiera quien lo escribió. La respuesta de otra API o de un modelo de IA puede cambiar sin aviso. TypeScript revisa tu código al compilar; cuando el programa corre, ya no ve nada. Si confías en el tipo, el error aparece tres funciones después, como un NaN en el total o un undefined al guardar.

La regla es revisar en la frontera: en el punto exacto donde el dato entra, una sola vez. Después de ese punto, el resto del código trabaja con un objeto que ya cumple el esquema y no vuelve a preguntar si quantity es un número. Validar a la mitad del código significa repartir if sueltos por varias funciones, que dejan de coincidir en cuanto alguien agrega un campo.

En una tienda hay tres entradas típicas: el formulario (el navegador), la ruta de API (el servidor) y las respuestas de servicios externos. La del servidor es la obligatoria. La del navegador ayuda a quien llena el formulario, pero cualquiera puede llamar a tu API sin pasar por él. Por la misma razón el CORS no protege tu API: lo que la protege es revisar cada petición en el servidor.

una puerta: el esquema revisa todo lo que entraentraesquematu código recibesafeParseOrderInputname: " Ana "name: "Ana"email: " ana@x.com "email: "ana@x.com"quantity: "2"quantity: 2quantity: "abc"rebota con 400price: 0se quitael navegador ayuda; el servidor decidevalida una vez, en la entradadespués de la puerta, todo es un OrderInput

Desliza la figura para verla completa

Definir el esquema

Un esquema de zod describe la forma del dato y sus reglas. Se instala con npm install zod; según su documentación, zod se prueba con TypeScript 5.5 o superior y exige strict en el tsconfig.json. Zod 4 es estable desde la 4.0.0, publicada el 9 de julio de 2025, y la 4.6.7 salió en npm el 12 de octubre de 2026. Este es el esquema de un pedido:

// lib/order-schema.ts
import * as z from "zod";

export const OrderInput = z.object({
  name: z.string().trim().min(2, "Escribe tu nombre completo"),
  email: z.string().trim().pipe(z.email("Revisa tu correo")),
  postalCode: z.string().trim().regex(/^\d{5}$/, "El código postal tiene 5 dígitos"),
  quantity: z.coerce.number("Escribe un número").int("Solo unidades enteras").min(1, "Pide al menos 1").max(10, "Máximo 10 por pedido"),
  notes: z.string().trim().max(500, "Notas: máximo 500 caracteres").optional(),
});

export type OrderInput = z.infer<typeof OrderInput>;
  1. import * as z from "zod" es la forma de importar que usa la documentación de zod 4.
  2. z.object define el objeto. Por defecto, las claves que no están en el esquema se quitan del resultado sin error, según la referencia de la API.
  3. name: .trim() quita los espacios antes de medir, y .min(2, "...") exige dos caracteres con un mensaje propio.
  4. email: primero recorta y luego, con .pipe(), pasa el texto limpio a z.email(). El orden importa: probamos z.email().trim() y rechaza " ana@example.com ", porque revisa el formato antes de recortar. Ese espacio final aparece cuando el teclado del móvil autocompleta, como vimos en el artículo de checkout móvil.
  5. postalCode: cinco dígitos con .regex(). Se guarda como texto para no perder el cero inicial de 06700.
  6. quantity: z.coerce.number() convierte el texto del formulario con Number(input). El mensaje que recibe sale cuando el resultado no es un número. Después, .int(), .min(1) y .max(10), cada uno con su mensaje.
  7. notes: opcional, con un máximo de 500 caracteres.
  8. z.infer saca el tipo del esquema. El tipo y el esquema se llaman igual, OrderInput: TypeScript permite un valor y un tipo con el mismo nombre, y así se importan juntos.

Estas son las validaciones que más se repiten en un formulario de tienda, con lo que cada una atrapa. Todas las corrimos con zod 4.6.7:

CampoEsquemaQué atrapa
Correoz.string().trim().pipe(z.email())Formato inválido y espacios del autocompletado
Cantidadz.coerce.number().int().min(1)"abc", 1.5 y el campo vacío, que se convierte en 0
Código postalz.string().regex(/^\d{5}$/)Letras y longitud; conserva el cero inicial
Método de envíoz.enum(["standard", "express"])Opciones que no están en tu lista
Casillaz.literal("on").optional()Marcada llega "on"; sin marcar no llega. No uses z.coerce.boolean(): convierte "false" en true
Enlacez.httpUrl()Solo http y https. z.url() aceptó javascript:alert(1) en nuestra prueba
Precio o totalNingunoNo lo aceptes del cliente: léelo de tu base de datos
validaciones comunes en un formulario de tiendacampozodqué atrapacorreoz.string().trim().pipe(z.email())formato, espacios de máscantidadz.coerce.number().int().min(1)"abc", 1.5 y "" (se vuelve 0)cód. postalz.string().regex(/^\d{5}$/)letras, longitud; guarda el 0envíoz.enum(["standard", "express"])opciones que no existencasillaz.literal("on").optional()no coerce.boolean: "false" da trueenlacez.httpUrl()z.url() deja pasar javascript:el precio no se valida: se lee de tu base de datosvalidación con zod 4 en la entradaprobado con zod 4.6.7 en Node 22, noviembre de 2026

Desliza la figura para verla completa

Usarlo en el formulario

En el navegador, el esquema revisa los datos antes de enviarlos, para mostrar el error junto al campo sin esperar al servidor. La función recibe un FormData, así no depende de React y se puede probar en Node:

// lib/check-order.ts
import * as z from "zod";
import { OrderInput } from "@/lib/order-schema";

// Runs in the browser before anything is sent: same schema as the API.
// Returns the clean order, or the messages for each field.
export function checkOrder(data: FormData) {
  const result = OrderInput.safeParse(Object.fromEntries(data));
  if (!result.success) {
    return { ok: false as const, errors: z.flattenError(result.error).fieldErrors };
  }
  return { ok: true as const, order: result.data };
}
  1. Object.fromEntries(data) convierte el FormData en un objeto de textos, como { quantity: "2" }. Todo llega como texto; por eso la cantidad usa z.coerce.
  2. safeParse no lanza excepciones: devuelve { success: true, data } o { success: false, error }, como explica la guía básica de zod. parse, en cambio, lanza un ZodError.
  3. Si falla, z.flattenError agrupa los mensajes por campo: { email: ["Revisa tu correo"] }.
  4. Si pasa, devuelve result.data: los textos ya recortados y la cantidad como número.

El componente conecta esa función con el formulario y con la API:

// components/OrderForm.tsx
"use client";
import { useState } from "react";
import { checkOrder } from "@/lib/check-order";

export function OrderForm() {
  const [errors, setErrors] = useState<Record<string, string[] | undefined>>({});

  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const checked = checkOrder(new FormData(event.currentTarget));
    if (!checked.ok) return setErrors(checked.errors);
    const res = await fetch("/api/orders", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(checked.order),
    });
    setErrors(res.status === 400 ? (await res.json()).fieldErrors : {});
  }

  return (
    <form onSubmit={onSubmit} noValidate>
      <label htmlFor="email">Correo</label>
      <input id="email" name="email" type="email" autoComplete="email"
        aria-invalid={Boolean(errors.email)} aria-describedby="email-error" />
      <p id="email-error">{errors.email?.[0]}</p>
      {/* name, postalCode, quantity and notes repeat the same pattern */}
      <button type="submit">Hacer pedido</button>
    </form>
  );
}
  1. noValidate apaga los avisos del navegador para que los mensajes salgan de un solo lugar: el esquema.
  2. En onSubmit, checkOrder revisa el formulario. Si hay errores, se guardan en el estado y no se envía nada.
  3. Si pasa, manda checked.order como JSON. Si el servidor responde 400, muestra sus fieldErrors, que tienen la misma forma que los del navegador.
  4. El campo enlaza su mensaje con aria-describedby y marca aria-invalid, para que un lector de pantalla lo anuncie.

Un detalle de peso: si importas el esquema en un componente con "use client", zod viaja al navegador. En nuestra prueba con zod 3 fueron 12.8 kB con gzip, como medimos en dónde poner use client. Si el tamaño importa, zod 4 trae Zod Mini (zod/mini), una variante con API de funciones pensada para recortarse mejor en el bundle.

un esquema, tres usoslib/order-schema.tsz.object({ … })formulariocheckOrder(formData)error junto al campoAPIsafeParse(body)inválido → 400tipoz.infer<typeof OrderInput>sin interface a manocambias el esquema, cambian los tresmismos mensajes en el navegador y en el servidor

Desliza la figura para verla completa

Usarlo en la API: rechazar con 400

La ruta de API es la puerta que no se puede saltar. En el App Router de Next.js es un route.ts con Request y Response estándar:

// app/api/orders/route.ts
import * as z from "zod";
import { OrderInput } from "@/lib/order-schema";

export async function POST(request: Request) {
  const body: unknown = await request.json().catch(() => null);
  const result = OrderInput.safeParse(body);
  if (!result.success) {
    return Response.json(z.flattenError(result.error), { status: 400 });
  }
  const order = result.data; // OrderInput: trimmed, typed, unknown keys dropped
  // Save the order here. Price and stock come from your database, not from the body.
  return Response.json({ ok: true, quantity: order.quantity }, { status: 201 });
}
  1. request.json() lanza si el cuerpo no es JSON válido. El .catch(() => null) lo convierte en null, y el esquema lo rechaza como a cualquier otro dato malo.
  2. body es unknown, no any: TypeScript no te deja usarlo hasta que pase por el esquema.
  3. Si falla, responde 400 con z.flattenError: formErrors para errores del objeto entero y fieldErrors por campo.
  4. Si pasa, result.data es un OrderInput. Un campo price que mandamos de más no llega: z.object lo quita.
  5. Precio y stock salen de tu base de datos, nunca del cuerpo de la petición.

Estas son las tres respuestas que dio la ruta al llamarla con objetos Request en Node 22:

// válido, con un "price": 0 de más
201 {"ok":true,"quantity":2}

// correo malo y 50 unidades
400 {"formErrors":[],"fieldErrors":{"email":["Revisa tu correo"],"quantity":["Máximo 10 por pedido"]}}

// cuerpo que no es JSON
400 {"formErrors":["Invalid input: expected object, received null"],"fieldErrors":{}}

400 (Bad Request) le dice a quien llamó que el problema está en lo que mandó y que repetir la misma petición no sirve. Si usaras parse sin try, la excepción terminaría en un 500, que dice lo contrario: que falló tu servidor. Evitar pedidos duplicados por reintentos es otro problema, el de la clave de idempotencia.

La misma puerta sirve para otras entradas. Cuando un modelo de IA llama a una de tus funciones, los argumentos llegan como JSON que tú no escribiste: revísalos con un esquema antes de tocar el carrito, como en function calling explicado con un carrito. Y cuando le pides a un modelo JSON válido con structured outputs, zod revisa lo que el esquema JSON no garantiza.

z.infer para el tipo

Sin zod, escribirías una interface a mano y un validador aparte, y tarde o temprano dejarían de coincidir. Con z.infer, el tipo sale del esquema: agregas un campo y TypeScript marca cada lugar que no lo maneja.

type OrderInput = z.infer<typeof OrderInput>;
// { name: string; email: string; postalCode: string;
//   quantity: number; notes?: string | undefined }

type OrderFormValues = z.input<typeof OrderInput>;
// lo mismo, pero quantity: unknown, porque z.coerce acepta cualquier entrada
  1. z.infer da el tipo de salida: lo que tienes después de validar. Es igual a z.output.
  2. z.input da el tipo de entrada. Con z.coerce la entrada es unknown; con .transform() los dos tipos también se separan.
  3. Comprobamos los dos tipos con una prueba de igualdad de tipos bajo tsc --strict.

Usa el tipo de salida en todo lo que viene después de la puerta: la función que guarda el pedido, el correo de confirmación, el cálculo del envío. Ninguna de ellas recibe unknown ni vuelve a validar.

Errores útiles para el usuario

Los mensajes por defecto están en inglés y hablan como programador: Too small: expected number to be >=1. Zod 4 trae traducciones; probamos z.config(z.locales.es()) y dio Inválido dirección de correo electrónico y Demasiado pequeño: se esperaba que número fuera >=1. Sirven para un log, no para quien está comprando.

Lo práctico es escribir el mensaje en cada regla. Según la página de mensajes de error, casi todas las funciones aceptan un texto, o un objeto { error: "..." }, y el mensaje de una regla gana sobre el del esquema. Por eso, en el esquema de arriba, "abc" da Escribe un número y "1.5" da Solo unidades enteras.

Para mostrarlos, la página de formato de errores describe tres funciones:

  • z.flattenError: mensajes por campo, para formularios planos como este.
  • z.treeifyError: un árbol con errors y properties, para objetos anidados.
  • z.prettifyError: un texto legible, para logs:
✖ Revisa tu correo
  → at email
✖ Máximo 10 por pedido
  → at quantity

Un buen mensaje dice qué hacer, no qué falló: "El código postal tiene 5 dígitos" en lugar de "Invalid string". Muestra cada mensaje junto a su campo, no en una lista arriba del formulario, y no muestres error.message tal cual: es un JSON con todos los problemas juntos.

Errores comunes

  • Validar solo en el navegador. Cualquiera puede llamar a la API sin el formulario. El servidor siempre valida.
  • Usar as OrderInput en lugar del esquema. Un as no revisa nada; solo calla al compilador.
  • parse sin try en una ruta. La excepción termina en un 500. Usa safeParse y responde 400.
  • Esperar undefined de un campo vacío. FormData manda "": .optional() lo deja pasar y z.coerce.number() lo vuelve 0.
  • z.coerce.boolean() para una casilla. Cualquier texto no vacío es true, incluido "false".
  • z.email().trim(). El formato se revisa antes de recortar; recorta primero y usa .pipe().
  • z.url() para enlaces que vas a mostrar. Acepta javascript:; usa z.httpUrl().
  • Una interface a mano junto al esquema. Se desincronizan. Saca el tipo con z.infer.

Preguntas frecuentes

¿Uso zod 3 o zod 4?

Zod 4 en un proyecto nuevo: es la versión estable desde julio de 2025 y la 4.6.7 es la última en npm al 19 de noviembre de 2026. Si tu proyecto sigue en la 3.25.x, ese paquete incluye zod 4 en "zod/v4", así que puedes migrar por partes.

¿parse o safeParse?

safeParse en las entradas, porque ahí un dato malo es normal y quieres responder con un 400 y los mensajes. parse sirve donde un dato malo es un error tuyo, como leer la configuración al arrancar: ahí conviene que el programa se detenga.

Si ya valido en el formulario, ¿tengo que validar en el servidor?

Sí. La validación del navegador es para que la persona corrija rápido; la del servidor es la que protege tus datos. Con un solo esquema no escribes nada dos veces: las dos usan el mismo archivo.

¿Cómo rechazo campos que no conozco?

z.object los quita sin error, lo que basta para guardar datos limpios. Si prefieres rechazar la petición, usa z.strictObject: con un price de más respondió Unrecognized key: "price".

Checklist

  • Cada entrada (formulario, API, servicio externo) pasa por un esquema, una sola vez.
  • El esquema vive en un archivo que importan el formulario y la ruta de API.
  • La ruta usa safeParse y responde 400 con z.flattenError.
  • El cuerpo se lee como unknown y el JSON malformado también da 400.
  • Los tipos salen de z.infer, sin interface a mano ni as.
  • Los textos se recortan antes de revisar el formato.
  • Cada regla tiene un mensaje que dice qué hacer, junto a su campo.
  • Precio, stock y totales se leen del servidor, nunca del cuerpo.

Con una sola puerta, el resto de tu código deja de dudar de sus datos. El siguiente paso es que el formulario sea cómodo de llenar en el teléfono: revisa el autocomplete y el teclado de cada campo.

Para que esos mensajes de error también los anuncie un lector de pantalla, revisa los formularios accesibles según WCAG 2.2.

¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026

← Blog