Implementar salidas estructuradas y validación

El texto libre es apropiado para prosa destinada a una persona. Si el resultado alimenta código, bases de datos, workflows o herramientas, necesitas una estructura explícita.

Structured Outputs puede obligar al modelo a ajustarse a un JSON Schema soportado por el proveedor. Eso mejora la fiabilidad sintáctica, pero no demuestra que el contenido sea verdadero, autorizado o coherente con las reglas de negocio.

Define una única fuente de verdad del esquema

El esquema debe expresar:

• campos obligatorios;
• tipos;
• enumeraciones;
• límites;
• objetos anidados;
• arrays;
• campos opcionales;
• restricciones que el formato permita.

Cuando el stack lo permita, genera o reutiliza el mismo contrato para:

• petición al modelo;
• parseo;
• validación;
• tipos;
• tests;
• documentación.

Evita tener cuatro versiones manuales del mismo esquema.

Entiende qué garantiza el formato

Un resultado puede cumplir JSON Schema y seguir siendo incorrecto:

{
  "customer_id": "cliente_de_otro_tenant",
  "priority": "alta",
  "amount": 999999
}

La forma es válida. La semántica y la autorización pueden ser falsas.

Por eso el pipeline correcto es:

modelo → parseo → validación estructural → validación semántica → reglas de negocio → permisos → dominio

No:

modelo → JSON válido → ejecutar

Trata todos los estados de salida

Modela:

• salida estructurada válida;
• rechazo;
• truncado;
• output incompleto;
• error de API;
• esquema no satisfecho;
• contenido semánticamente inválido.

No deserialices y continúes como si cualquier respuesta estructurada fuese una orden válida.

Valida evidencia

Si el modelo extrae o clasifica información a partir de documentos, conserva referencias a la evidencia.

Por ejemplo:

field: total
value: 1.245,50
evidence:
  document_id
  page
  span

El servidor puede comprobar que la referencia existe y que pertenece a contenido autorizado. Una revisión humana puede comprobar si realmente sostiene el valor.

Repara de forma limitada

Una salida mal formada puede justificar un reintento. Una salida con ausencia de evidencia no debe «repararse» inventando contenido.

Clasifica el motivo:

• error de forma;
• dato ausente;
• ambigüedad;
• contradicción;
• catálogo desconocido;
• permiso;
• proveedor.

Define un máximo de intentos. Si el fallo persiste, escala, solicita información o devuelve un estado de revisión.

Usa esquemas pequeños

No fuerces un único megaobjeto para una tarea que tiene fases distintas. A veces es más mantenible usar contratos separados:

clasificación → extracción → decisión → acción

Cada fase tiene un propósito y una validación más fácil de razonar.

Ejemplo: extracción de factura

El modelo devuelve proveedor, fecha, total, moneda y referencia de evidencia.

El servidor comprueba:

• que moneda pertenece al catálogo;
• que total >= 0;
• que la evidencia pertenece al documento;
• que la fecha es coherente;
• que el proveedor se resuelve contra el ERP;
• que el usuario tiene permiso;
• que campos críticos no están ausentes.

Solo después se crea una entidad de dominio.

Distingue estructura externa e interna

El esquema que pides al modelo no tiene por qué ser idéntico a la entidad de base de datos.

Puede ser más seguro recibir:

supplier_name
invoice_date
total
evidence

y después resolver supplier_id en servidor.

Así evitas que el modelo invente claves internas.

Diseña catálogos controlados

Si el output contiene una categoría de negocio, el servidor debe tener un catálogo vigente.

Cuando el modelo devuelve una categoría desconocida:

• no la cree automáticamente;
• marca revisión;
• registra el caso.

Esto previene proliferación de valores.

Trata null y ausencia de forma semántica

null, campo ausente y cadena vacía pueden significar cosas distintas.

Define:

• no encontrado;
• no aplicable;
• ambiguo;
• no autorizado.

No uses un único valor para todos.

Versiona schemas

Cuando cambias un contrato:

• incrementa versión;
• conserva tests;
• migra consumidores;
• maneja jobs pendientes.

Un schema es una API interna.

Añade invariantes cruzadas

Algunas reglas involucran varios campos:

if currency == "EUR" then country must be compatible...
end_date >= start_date
subtotal + tax ≈ total

JSON Schema puede expresar parte de estas restricciones, pero la lógica de negocio seguirá existiendo fuera.

Registra motivos de rechazo

No guardes solo «validation failed».

Registra:

• campo;
• regla;
• valor;
• severidad;
• versión.

Esto permite convertir fallos en datos de evaluación.

Evalúa drift del esquema

Tras cambiar modelo o prompt, mide:

• tasa de outputs inválidos;
• campos null;
• categorías desconocidas;
• reparaciones;
• retries.

Una subida puede indicar degradación aunque la aplicación siga funcionando.

Ejercicio

Construye un contrato para una tarea real e incluye:

1. JSON Schema;
2. parser;
3. validación semántica;
4. regla de negocio;
5. permiso;
6. evidencia;
7. rechazo;
8. truncado;
9. reparación limitada;
10. batería de casos inválidos.

Prueba al menos: campo extra, campo ausente, enum desconocido, objeto válido con ID no autorizado, salida parcial y dato plausible sin evidencia.

Resultado de la lección

Debes terminar con un pipeline donde Structured Outputs controla la forma, pero el servidor conserva la autoridad sobre significado, permisos y efectos. Esa distinción será crítica en la siguiente lección, cuando el modelo pueda solicitar herramientas.