Herramientas mencionadas en este artículo
Abre la herramienta en el navegador mientras lees y prueba el flujo al instante.
Para ti, que sientes que las definiciones de tipo por sí solas no son suficientes
Has escrito tu código en TypeScript, has organizado perfectamente tus definiciones de tipo y tienes cero errores de compilación. Sin embargo, en tiempo de ejecución, tu aplicación se bloquea porque llegó una estructura de datos inesperada de una API. ¿Te suena familiar?

Lo más importante que debes recordar es que los tipos de TypeScript solo existen en tiempo de compilación; desaparecen una vez que tu código se ejecuta en el navegador. Esto significa que la única forma de estar seguro de que los datos externos son correctos es verificarlos en tiempo de ejecución.
Zod: Llevando la seguridad de tipos al “tiempo de ejecución”
Aquí es donde entra Zod.
Zod te permite definir un “esquema” (un plano) para tus datos y lo valida estrictamente en tiempo de ejecución.
- Bloquea datos no válidos en la entrada: Si esperas un
stringpero recibes unnull, Zod lanza inmediatamente un error, protegiendo el resto de la lógica de tu aplicación. - Obtén definiciones de tipo gratis: Una vez que defines un esquema, puedes extraer automáticamente el tipo de TypeScript correspondiente con
z.infer<T>.
Escritura de esquemas sin esfuerzo
Aunque Zod es increíblemente potente, escribir manualmente esquemas complejos para que coincidan con objetos JSON anidados puede ser una tarea tediosa.
Nuestro Generador de JSON a Zod fue creado para eliminar la fricción de la definición de esquemas. Simplemente pega tu JSON y generará instantáneamente el esquema de Zod correspondiente para ti. Si ya dispone de un JSON Schema o de una definición OpenAPI, el conversor JSON Schema ⇄ Zod es más preciso: conserva los campos obligatorios y los formatos que un valor de ejemplo no puede indicar.
Flujo de trabajo básico
- Copia el JSON devuelto por tu API.
- Pégalo en la herramienta para generar un esquema de Zod (
z.object({...})). - Pega el código generado en tu proyecto y ¡empieza a validar con
Schema.parse(data)!
import { z } from 'zod';
// Esquema generado por la herramienta
const UserSchema = z.object({
id: z.number(),
name: z.string(),
});
// Realiza la verificación en tiempo de ejecución y la extracción de tipos simultáneamente
type User = z.infer<typeof UserSchema>;
const safeData = UserSchema.parse(rawData);
Reglas de generación: leer la salida real
Mirar el esquema generado a partir del siguiente JSON muestra cómo infiere los tipos la herramienta.
{
"users": [
{ "id": 1, "name": "Ada", "email": "a@example.com", "score": 10 },
{ "id": 2, "name": "Bob", "score": 9.5, "deletedAt": null }
],
"tags": [],
"meta": { "created-at": "2026-01-01T00:00:00Z", "page": 1, "note": null },
"mixed": [1, "a"],
"empty": {}
}
La salida es:
import { z } from 'zod';
const schema = z.object({
users: z.array(z.object({
id: z.number(),
name: z.string(),
email: z.string().optional(),
score: z.number(),
deletedAt: z.null().optional(),
})),
tags: z.array(z.unknown()),
meta: z.object({
"created-at": z.string(),
page: z.number(),
note: z.null(),
}),
mixed: z.array(z.union([z.number(), z.string()])),
empty: z.object({}),
});
type Schema = z.infer<typeof schema>;
- La salida tiene tres partes: el
import,const schema = …ytype Schema = z.infer<typeof schema>. Cambie el nombre deschema/Schemapor el que prefiera tras generar. - Los enteros y los decimales se convierten en
z.number()(incluso cuando se mezclan10y9.5, como enscore). Si quiere solo enteros, cámbielo a mano az.number().int(). - Los arreglos combinan la forma de todos sus elementos en una. Una clave que solo tienen algunos elementos (
email) pasa a ser.optional(). Una clave cuyos únicos valores sonnull(deletedAt) pasa a serz.null().optional(), así que corríjala a mano al tipo real. - Un arreglo que mezcla tipos distintos de valores se convierte en
z.union([...]). «Algo, onull» usa.nullable(). - Un arreglo vacío es
z.array(z.unknown())y un objeto vacío esz.object({}). Sin elementos en la muestra, no se puede determinar el tipo. - Una clave que no se puede escribir como identificador, como
created-at, se emite entre comillas. - Una cadena de fecha y hora (
"2026-01-01T00:00:00Z") también esz.string(). Si quiere una validación estricta conz.string().datetime(), cámbielo a mano.
Un ejemplo práctico con respuestas de API
En la práctica ocurren pequeñas discrepancias: un campo de una API de listado llega como null, una fecha llega como cadena, un ID numérico se convierte en cadena.
{
"id": "123",
"name": "Ada",
"lastLoginAt": null
}
El esquema generado a partir de este JSON no se usa tal cual: lo ajustas a la especificación. Si quieres convertir id a número, usa z.coerce.number(); si una hora de inicio de sesión ausente es aceptable, usa z.string().datetime().nullable(). Genera el primer borrador con la herramienta y deja que una persona revise solo los casos límite: así reduces errores manuales mientras te ajustas a la API real.
Conclusión
Proteger los límites de tus datos es proteger la estabilidad de tu sistema.
Convierte el “debería estar bien” en un “estabilidad verificada” con Zod. Deja que una herramienta se encargue del trabajo manual de definir el esquema para que puedas concentrarte en construir la lógica principal de tu aplicación.
Novedades de noviembre de 2026
- El mismo JSON también puede producir un esquema de Valibot y un JSON Schema (draft 2020-12). Se aplican la opción de formatos de cadena (fecha-hora, email, UUID, URL) y el nombre raíz.
- Los elementos de un array se fusionan y las claves ausentes en algunos objetos pasan a ser opcionales (
v.optionalen Valibot, fuera derequireden JSON Schema).
Preguntas frecuentes
Si tengo tipos de TypeScript, ¿necesito Zod?
Los tipos de TypeScript solo existen en tiempo de compilación y desaparecen en tiempo de ejecución. No hay garantía de que “los datos que vienen de fuera” —API externas, entradas de formulario— coincidan con tus tipos, así que necesitas un validador en tiempo de ejecución como Zod. Con Zod, z.infer también te da el tipo, de modo que no gestionas tipos y validación por duplicado.
Si Zod también genera tipos, ¿sigo necesitando JSON a TypeScript?
Si necesitas validación en tiempo de ejecución, derivar el tipo de un esquema Zod con z.infer es el enfoque conveniente de fuente única. Si solo necesitas tipos para datos internos de confianza sin validación, el conversor de JSON a TypeScript es más simple. Elige según el caso.
¿Puedo usar el esquema generado tal cual?
Funciona como primer borrador, pero se recomienda ajustarlo a la especificación real de la API. Usa z.coerce.number() para convertir cadenas numéricas, .nullable() para valores que pueden ser null y .optional() para campos opcionales. Dejar que una persona revise solo los casos límite reduce los errores manuales.
