Category: Zod

Saber cómo tipar las respuestas de una LLM con Zod + TypeScript aparece en las primeras líneas porque es lo que evita que un agente, workflow o microservicio se rompa en producción. El modelo devuelve JSON, a menudo; nunca con la forma exacta que esperabas. .parse() y z.infer<> no son trucos: son la defensa que convierte datos inciertos en contratos verificables.

Resumen rápido (lectores con prisa)

Qué: Usa Zod para validar y transformar respuestas de LLM en runtime.

Cuándo: Siempre que vayas a persistir datos o ejecutar acciones críticas basadas en la salida de una LLM.

Por qué importa: TypeScript no valida en runtime; sin validación, datos malformados pueden romper sistemas en producción.

Cómo funciona: Diseña el esquema Zod como fuente única, extrae tipos con z.infer<>, limpia la salida si es necesario y valida con .parse() o .safeParse().

Por qué JSON.parse() + as es una trampa (y qué rompe)

El patrón clásico:

const obj = JSON.parse(response) as MyType;

Es práctico. Es una mentira. TypeScript desaparece en runtime; as no valida nada. Los fallos típicos de LLMs:

Si confías en casts, esos problemas llegan a tu base de datos o a la lógica que ejecuta acciones. Validación en runtime es obligatoria.

El patrón sólido: esquema primero, prompt segundo

Este patrón convierte la salida estocástica de la LLM en una entrada controlada para tu sistema.

Ejemplo práctico mínimo

import { z } from 'zod';

const TaskSchema = z.object({
  title: z.string().min(5),
  priority: z.enum(['low','medium','high']),
  estimatedHours: z.number().positive().optional(),
});

type Task = z.infer;

Al pedir al modelo que devuelva JSON, serializa el esquema (o su forma) en el prompt para guiar la salida.

Limpieza defensiva y parse()

Los LLMs suelen añadir markdown. Limpia antes de parsear:

function cleanJson(raw: string) {
  return raw.replace(/```json\n?|\n?```/g, '').trim();
}

const parsed = JSON.parse(cleanJson(rawOutput));
const valid = TaskSchema.parse(parsed); // lanza ZodError si falla

Usa .parse() cuando quieras detener el flujo y tratar la anomalía como error severo (útil en endpoints HTTP que deben devolver 4xx/5xx claros).

.safeParse() y auto‑corrección de prompts

En agentes autónomos o workflows escalables (n8n, agentes con herramientas), es preferible no lanzar. .safeParse() devuelve { success, data?, error? } para manejar fallos:

const result = TaskSchema.safeParse(parsed);
if (!result.success) {
  // registrar, emitir métricas y reintentar con autocorrección
  const zodErrors = result.error.flatten();
  // reintentar: enviar a la LLM el error y pedir JSON corregido
}

Patrón de autocorrección: incluye los errores de Zod en un nuevo prompt — el LLM suele corregir la estructura en el siguiente intento.

Structured Outputs no elimina Zod

Structured Outputs de OpenAI ayuda a reducir errores de formato (Structured Outputs). Aun así:

Zod sigue siendo la última línea de defensa.

Operativa en producción: logging, reintentos y SLOs

Esto transforma un fallo LLM en un incidente manejable, no en una caída silenciosa.

Consejos prácticos y anti‑patrones

Conclusión técnica

Tipar las respuestas de una LLM con Zod + TypeScript no es una cuestión de estilo: es ingeniería de fiabilidad. .parse() y z.infer<> convierten la salida no determinista de una IA en datos verificables. Si construyes agentes, pipelines en n8n o features que actúan sobre sistemas críticos, aplicar este patrón es la diferencia entre sistemas que escalan y sistemas que requieren vigilancia humana constante. Implementa el esquema primero, valida siempre y deja que la LLM vuelva a intentarlo cuando falle — pero que falle donde tú lo controles.

Para equipos que implementan flujos autónomos y pipelines de IA, una práctica útil es centralizar patrones de validación y autocorrección; esto es exactamente el tipo de trabajo que se experimenta en Dominicode Labs, donde se documentan plantillas y prácticas para agentes y workflows.

¿Confías en TypeScript para proteger tu app en producción? Deja de hacerlo. TypeScript es un analizador estático; su trabajo termina cuando el código se compila. Si quieres seguridad real en ejecución necesitas otra cosa. Aquí va la guía práctica: Zod vs TypeScript puro: cuándo usar validación en runtime.

Resumen rápido (lectores con prisa)

Qué es: Zod es una librería de validación y parsing en runtime; TypeScript es un sistema de tipos estático.

Cuándo usarlo: Usa Zod en las fronteras (endpoints, webhooks, env, uploads); usa TypeScript dentro del dominio.

Por qué importa: TypeScript sufre type erasure y no impide fallos en producción; Zod parsea y falla rápido.

Cómo usarlo: Definir esquemas Zod, derivar tipos con z.infer y parsear payloads en los handlers.

Por qué TypeScript no basta (y dónde duele más)

TypeScript tiene un problema estructural: Type Erasure. Los tipos desaparecen al compilar. Eso significa que las aserciones (as T) son mentiras que el compilador acepta y la app paga en runtime.

interface Usuario { id: number; email: string; }

const datos = await respuesta.json() as Usuario;
console.log(datos.email.toLowerCase()); // Boom si email no existe

Si la API cambia, o devuelve HTML en un error 500, tu código explota. TypeScript no está ahí para detenerlo.

Zod y el principio “Parse, don’t validate”

Zod opera en runtime. Su filosofía es clara: no intentes “validar” por inercia; parsea y falla rápido.

import { z } from 'zod';

const UsuarioSchema = z.object({
  id: z.number(),
  email: z.string().email(),
});

type Usuario = z.infer;

const res = await fetch(url);
const raw = await res.json();
const usuario = UsuarioSchema.parse(raw); // lanza si algo falla
console.log(usuario.email.toLowerCase());

Con z.infer mantienes una sola fuente de verdad: el esquema. Nada de duplicar interfaces y validadores.

safeParse vs parse

Si quieres manejo de errores controlado:

const result = UsuarioSchema.safeParse(raw);
if (!result.success) {
  // logging, métricas, respuesta 400 al cliente...
  throw new Error('Payload inválido');
}
const usuario = result.data;

safeParse devuelve un objeto con success y error para flujos menos crudos.

Dónde aplicar validación (regla práctica)

No todo necesita Zod. La regla del arquitecto es simple:

Aplicar Zod en todas partes degrada rendimiento y readability. No validar en las fronteras te expone a fallos catastróficos.

Casos prácticos y patterns

1) Respuesta API (backend → frontend o backend → backend)

2) Webhooks / n8n / automatizaciones

3) Variables de entorno en arranque (ejemplo con Zod)

const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development','production']),
});
const env = EnvSchema.parse(process.env);

Arranque fallido = fallo visible y evitar estados inconsistentes.

4) Formularios en frontend

Integra Zod con React Hook Form para validar antes de mutar el estado o enviar al servidor.

Coste y alternativas: cuándo preocuparse por rendimiento

Zod añade CPU y peso al bundle. En la mayoría de apps esto es irrelevante frente a la estabilidad que gana tu producto. En sistemas de altísima demanda (millones de eventos por segundo) evalúa alternativas más ligeras o validaciones a medida.

Alternativas emergentes existen, pero la elección debe basarse en mediciones. No te cases con una librería sin perf tests en tu caso real.

Integración práctica: patrón recomendado

Conclusión y pasos accionables

Recuerda: el compilador no vive en producción. Tú sí. Protege lo que importa.

Prueba esto ahora: añade un esquema Zod a uno de tus endpoints y corre safeParse con un payload inesperado. Verás la diferencia. Esto no acaba aquí; la próxima nota tratará cómo estructurar esquemas Zod para versiones y migraciones sin romper consumidores.

FAQ