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)
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.
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>;
import * as z from "zod"es la forma de importar que usa la documentación de zod 4.z.objectdefine 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.name:.trim()quita los espacios antes de medir, y.min(2, "...")exige dos caracteres con un mensaje propio.email: primero recorta y luego, con.pipe(), pasa el texto limpio az.email(). El orden importa: probamosz.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.postalCode: cinco dígitos con.regex(). Se guarda como texto para no perder el cero inicial de06700.quantity:z.coerce.number()convierte el texto del formulario conNumber(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.notes: opcional, con un máximo de 500 caracteres.z.infersaca 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:
| Campo | Esquema | Qué atrapa |
|---|---|---|
| Correo | z.string().trim().pipe(z.email()) | Formato inválido y espacios del autocompletado |
| Cantidad | z.coerce.number().int().min(1) | "abc", 1.5 y el campo vacío, que se convierte en 0 |
| Código postal | z.string().regex(/^\d{5}$/) | Letras y longitud; conserva el cero inicial |
| Método de envío | z.enum(["standard", "express"]) | Opciones que no están en tu lista |
| Casilla | z.literal("on").optional() | Marcada llega "on"; sin marcar no llega. No uses z.coerce.boolean(): convierte "false" en true |
| Enlace | z.httpUrl() | Solo http y https. z.url() aceptó javascript:alert(1) en nuestra prueba |
| Precio o total | Ninguno | No lo aceptes del cliente: léelo de tu base de datos |
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 };
}
Object.fromEntries(data)convierte elFormDataen un objeto de textos, como{ quantity: "2" }. Todo llega como texto; por eso la cantidad usaz.coerce.safeParseno lanza excepciones: devuelve{ success: true, data }o{ success: false, error }, como explica la guía básica de zod.parse, en cambio, lanza unZodError.- Si falla,
z.flattenErroragrupa los mensajes por campo:{ email: ["Revisa tu correo"] }. - 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>
);
}
noValidateapaga los avisos del navegador para que los mensajes salgan de un solo lugar: el esquema.- En
onSubmit,checkOrderrevisa el formulario. Si hay errores, se guardan en el estado y no se envía nada. - Si pasa, manda
checked.ordercomo JSON. Si el servidor responde 400, muestra susfieldErrors, que tienen la misma forma que los del navegador. - El campo enlaza su mensaje con
aria-describedbyy marcaaria-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.
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 });
}
request.json()lanza si el cuerpo no es JSON válido. El.catch(() => null)lo convierte ennull, y el esquema lo rechaza como a cualquier otro dato malo.bodyesunknown, noany: TypeScript no te deja usarlo hasta que pase por el esquema.- Si falla, responde 400 con
z.flattenError:formErrorspara errores del objeto entero yfieldErrorspor campo. - Si pasa,
result.dataes unOrderInput. Un campopriceque mandamos de más no llega:z.objectlo quita. - 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
z.inferda el tipo de salida: lo que tienes después de validar. Es igual az.output.z.inputda el tipo de entrada. Conz.coercela entrada esunknown; con.transform()los dos tipos también se separan.- 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 conerrorsyproperties, 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 OrderInputen lugar del esquema. Unasno revisa nada; solo calla al compilador. parsesintryen una ruta. La excepción termina en un 500. UsasafeParsey responde 400.- Esperar
undefinedde un campo vacío.FormDatamanda"":.optional()lo deja pasar yz.coerce.number()lo vuelve 0. z.coerce.boolean()para una casilla. Cualquier texto no vacío estrue, 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. Aceptajavascript:; usaz.httpUrl().- Una
interfacea mano junto al esquema. Se desincronizan. Saca el tipo conz.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
safeParsey responde 400 conz.flattenError. - El cuerpo se lee como
unknowny el JSON malformado también da 400. - Los tipos salen de
z.infer, sininterfacea mano nias. - 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

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