English

Deja de pedir JSON por favor — define un esquema

Le pides JSON a una IA y estás apostando. Le pides un campo anidado dos niveles de profundidad y puede aplanarlo. Le pides exactamente tres claves y puede agregar una cuarta "servicial" que nunca solicitaste. Terminas escribiendo código de parseo defensivo para atrapar lo que el modelo no te dio del todo bien. Nada de eso es necesario una vez que dejas de describir la forma en español y empiezas a definirla como datos.

El problema de pedir estructura con prompts

"Por favor responde en JSON válido con los campos name, email y orders" se lee como una especificación, pero el modelo lo trata como cualquier otra instrucción: una sugerencia fuerte, no un contrato. En la práctica esto falla de maneras predecibles — un campo anidado se aplana o se renombra, aparece una clave description o note no solicitada porque el modelo pensó que estaba siendo servicial, o un campo del que el modelo no estaba seguro se omite en lugar de dejarse en null. Cada uno de estos es una sorpresa en tiempo de ejecución que tu código tiene que detectar y manejar después.

La causa de raíz es que las instrucciones de formato en lenguaje natural son solo tokens de texto mezclados con todo lo demás en el prompt. El modelo no tiene ningún mecanismo que lo obligue a obedecerlas — está haciendo coincidencia de patrones sobre "esto parece una solicitud con forma de JSON", no ejecutando un esquema.

Por qué el modo esquema sí funciona

Los structured outputs invierten el mecanismo. En lugar de describir la forma con palabras, le entregas a la llamada del modelo un objeto de esquema real — un esquema de Zod, un modelo de Pydantic o un documento JSON Schema en crudo — a través de un parámetro construido exactamente para este propósito. El proveedor del modelo entonces restringe la propia generación, o valida y reintenta, para que la respuesta se ajuste a ese esquema antes de que el código de tu aplicación la vea. No estás esperando que el modelo haya entendido tu descripción; le estás entregando un contrato al que está atado mecánicamente.

Esto difiere de las instrucciones de formato en tres formas concretas:

1. Los tipos se imponen, no se sugieren. Un campo tipado como número no puede volver como la cadena "42".
2. Los campos requeridos no pueden desaparecer en silencio. El punto de imposición es el paso de generación/validación, no una expresión regular esperanzada de tu lado.
3. La guía a nivel de campo se mueve al esquema. Instrucciones como "menos de 200 caracteres, audiencia general" se convierten en una descripción sobre el propio campo del esquema en vez de texto repetitivo en el prompt.

Cómo hacerlo

La mayoría de los SDKs modernos de IA exponen una llamada de "generar structured output" o "generar objeto" que toma tu prompt normal más un parámetro de esquema, separado del texto del prompt:

schema = {
  name: string,
  email: string,
  orders: [{ id: string, total: number }]
}

result = model.generateObject({
  prompt: "Extract the customer record from this email...",
  schema: schema,
})

# result.object is validated — no parsing, no defensive code

El patrón es el mismo entre proveedores y librerías: define el esquema una vez, pásalo junto al prompt y lee de vuelta un objeto validado en lugar de una cadena cruda. Muchos SDKs también exponen un modo strict que restringe con fuerza la generación al esquema en vez de validar-y-reintentar después — vale la pena activarlo si tu librería lo soporta.

Dónde rinde frutos

• Extraer datos estructurados de texto no estructurado — sacar un registro de cliente, una factura o un currículum de una entrada de formato libre.
• Respuestas de API de las que depende código posterior — se acabaron los guardias porque una clave podría faltar.
• Clasificación y enrutamiento — ordenar tickets de soporte, etiquetar contenido, elegir una herramienta a invocar. Un campo tipado como enum significa que el modelo literalmente no puede devolver una categoría fuera de tu lista.

Trucos avanzados

• No confíes en un benchmark publicado para tu esquema. Un modelo que alcanza alto cumplimiento de esquema en el conjunto de evaluación de un proveedor puede aun así portarse mal con tus datos — profundidad de anidamiento inusual, patrones de nombres de campos o enums específicos de tu dominio son exactamente donde los modelos divergen de los benchmarks. Prueba contra entradas reales antes de enviar.
• Un esquema valida la forma, no el significado. El modelo puede devolver un valor sintácticamente válido pero factualmente incorrecto. El modo esquema elimina una clase de errores de parseo, no la alucinación.
• Mantén los esquemas ajustados. Un esquema grande con nombres de campos vagos le da al modelo menos señal que uno enfocado con descripciones claras por campo — trata el diseño del esquema como diseño de prompt.

Recursos

• Structured Outputs / la generación restringida por JSON Schema está documentada en los principales SDKs de IA y APIs de proveedores — consulta la documentación de "structured outputs" o "generate object" de tu proveedor.
• Zod (TypeScript) y Pydantic (Python) son las librerías de esquema más comunes emparejadas con estas APIs.