Simplifique la validación de JSON con Zod

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 string pero recibes un null, 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.

Flujo de trabajo básico

1. Copia el JSON devuelto por tu API.
2. Pégalo en la herramienta para generar un esquema de Zod (z.object({...})).
3. 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);

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.

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.