Salidas estructuradas de LLM que se rompen: cómo escribir de verdad el Schema para el modo strict
En resumen: Activar strict sobre un JSON Schema cualquiera acaba casi siempre en un 400: todos los campos required, additionalProperties:false en cada objeto, y $ref y allOf rechazados al instante. Esta guía muestra cómo reescribir un esquema permisivo en una versión compatible con strict — con uniones nullable, límites duros y checklist sobre refusal.

Lo esencial: strict: true no es un interruptor "sé más riguroso" — es un contrato que solo acepta un subconjunto de JSON Schema. Todos los campos required, additionalProperties: false en cada objeto, $ref y allOf prohibidos al instante. Si envías el esquema en modo strict sin reescribirlo, la respuesta es un 400, no una salida confiable.
En la práctica diaria la escena se repite igual: el equipo tiene un esquema bien diseñado, con campos opcionales, $defs reutilizables y additionalProperties abierto por compatibilidad. Después alguien añade "strict": true a la llamada de la API, convencido de que ahora el modelo "respetará" el esquema. El resultado inmediato es un error 400 con un mensaje largo, o peor: un esquema aceptado que produce salidas inesperadas. El modo strict no interpreta el esquema con indulgencia: lo reescribe desde cero en una gramática que el motor de generación puede seguir al pie de la letra, y todo lo que no quepa en esa gramática se rechaza o se ignora en silencio. Entender qué reglas tienen vigor real, antes de enviar la petición, es la diferencia entre un pipeline estable y una semana de depuración.
Modo strict = tu JSON Schema se compila en una gramática que el modelo debe seguir palabra por palabra. Todo lo que la gramática no puede expresar se rechaza al enviar o se ignora en silencio — y en ambos casos el problema aparece después de que el usuario ya lo ha visto.
Cómo funciona de verdad el motor del modo strict
Los modelos no leen tu JSON Schema como lo haría un validador tradicional. Cuando strict: true está activo, el esquema se transforma en una gramática restringida — un autómata de estados finitos que decide, token a token, qué continuaciones son legales. El modelo solo genera transiciones permitidas por el autómata; no hay un control posterior que corrija la salida, la corrección es estructural.
Esta arquitectura explica todos los comportamientos que parecen misteriosos. Si un campo no está incluido en required, el autómata debe decidir cuándo detenerse: la única solución segura es dar al modelo la libertad de emitir null, así que el esquema efectivo que recibe el motor tendrá ese campo siempre presente. Si un objeto admite propiedades adicionales, el autómata no puede anticipar qué claves aparecerán, así que cada objeto debe cerrarse rígidamente. Cada "prohibido" de la documentación nace de un límite concreto de este autómata, no de una elección estilística de OpenAI.
La segunda consecuencia es más insidiosa: algunas palabras clave de JSON Schema (como pattern, minLength, maximum) son válidas para el esquema pero no se aplican por la gramática. El esquema se acepta, la respuesta llega limpia, pero la restricción nunca se ha respetado. Es la forma más silenciosa de romper un pipeline: la validación posterior falla en producción y ningún log muestra un error de esquema.
Las tres reglas innegociables
Si tienes tiempo de arreglar solo una cosa, arregla estas tres. Resuelven la gran mayoría de los 400.
1. Todos los campos en required, siempre. En modo strict cada clave declarada en properties debe aparecer en required — también las opcionales. El truco oficial para decir "opcional" es una unión nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Así el autómata sabe exactamente cuándo la clave es legal, y el modelo expresa "no hay cupón" con null en lugar de omitir la clave.
2. additionalProperties: false en cada objeto. No solo en el objeto raíz: cada objeto anidado, sin excepciones. Un solo nivel abierto vuelve todo el esquema no conforme.
3. $ref y allOf prohibidos. Sin referencias, sin $defs, sin composición. El esquema debe estar completamente expandido, un único árbol autónomo. if/then/else y oneOf en la raíz comparten el mismo destino.
Tabla de términos prohibidos e ineficaces
| Palabra clave | Resultado en modo strict | Sustitución recomendada |
|---|---|---|
$ref, $defs |
Rechazo con 400 | Expansión completa del esquema |
allOf |
Rechazo con 400 | Unión manual de propiedades |
if/then/else |
Rechazo con 400 | enum + gestión en el cliente |
oneOf en la raíz |
Problemas / respuesta no conforme | Un solo objeto raíz |
Campo fuera de required |
Se vuelve siempre obligatorio | Unión nullable ["string", "null"] |
pattern, minLength |
Esquema aceptado pero restricción ignorada | Validación explícita tras la respuesta |
maximum, format |
Esquema aceptado pero restricción ignorada | Verificación en la aplicación |
La fila más peligrosa es la última pareja: el esquema pasa la validación pero la restricción no existe. Si tu lógica confía en pattern, estás construyendo sobre arena.
Los límites duros que nadie lee
Antes de escribir el esquema, comprueba que estás dentro de estas fronteras — superarlas produce errores genéricos difíciles de diagnosticar:
| Restricción | Máximo |
|---|---|
| Propiedades totales por esquema | 5000 |
| Profundidad de anidamiento | 10 niveles |
| Tamaño de la cadena del esquema | 120.000 caracteres |
| Valores enum totales | 1000 |
Los esquemas generados automáticamente desde frameworks o definiciones OpenAPI a menudo superan estos límites sin que nadie lo note: 6000 propiedades en total, 12 niveles de anidamiento, 1500 valores enum dispersos. El mensaje de error de la API rara vez indica qué umbral se ha superado, así que conviene comprobarlo uno mismo antes de enviar.
Reescritura automática: script make_strict
Para esquemas grandes, la reescritura manual no es práctica. Este script en Python recorre el árbol y aplica las tres reglas de forma recursiva:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# cada propiedad se vuelve required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# los campos "opcionales" debes marcarlos nullable tú, antes
# elimina lo que strict no acepta
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Dos advertencias. Primera: el script no adivina qué campos eran opcionales — tendrás que marcar las uniones nullable tú mismo, preferiblemente en la fuente del esquema y no en el resultado. Segunda: tras la transformación, ejecuta siempre una petición de prueba: la expansión puede superar los límites de tamaño o de propiedades que antes respetabas.
El camino equivalente en Anthropic
Anthropic no expone una bandera strict, pero alcanza el mismo resultado mediante el mecanismo tool: la definición de la herramienta actúa como esquema, y el modelo queda ligado a su forma. El enfoque es prácticamente idéntico:
const tool = {
name: "extract_invoice",
description: "Extrae los datos de la factura del texto",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// el modelo responde con una llamada tool conforme
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
La regla práctica es la misma: también en Anthropic, cada objeto necesita required completo y additionalProperties: false. La diferencia está en el canal de respuesta — tool_use en vez de contenido textual — y en que el campo refusal es específico de OpenAI.
Refusal, truncamiento y forma rota: tres averías, tres remedios
Incluso con un esquema perfecto, la salida puede fallar por tres motivos distintos, y confundirlos es la forma más rápida de perder un día:
1. refusal no vacío. OpenAI, en modo strict, puede devolver un campo refusal con el motivo por el que declinó la petición. No es un error de esquema — es el modelo que rechaza semánticamente la tarea. El remedio es revisar el prompt o la política, no el esquema.
2. Truncamiento por max_tokens. La generación se interrumpe a mitad de cadena y el JSON no se cierra. En modo strict la respuesta, si llega, es conforme — pero si el presupuesto de tokens se agota, llega recortada. Sube max_tokens o reduce el tamaño esperado de la salida. Para escenarios recurrentes, la reparación automática del JSON truncado ofrece patrones listos para usar.
3. Forma rota no conforme. El esquema era abierto (propiedades adicionales permitidas, campos fuera de required) y strict no estaba activo: el modelo produce JSON válido que no respeta el contrato. El remedio es reescribir el esquema como en esta guía, no añadir controles posteriores a la generación.
El diagnóstico correcto empieza siempre por distinguir estos tres casos: mirar el campo finish_reason, la presencia de refusal, y comparar la respuesta con el esquema realmente enviado.
Checklist final antes de pasar a producción
| Punto de control | Qué verificar |
|---|---|
required completo |
Cada propiedad declarada está en required |
| Nullable explícito | Los campos opcionales son uniones ["...", "null"] |
additionalProperties: false |
En cada objeto, no solo en la raíz |
Cero $ref / allOf / if-then-else |
Esquema completamente expandido |
| Límites respetados | ≤ 5000 propiedades, ≤ 10 niveles, ≤ 120k caracteres |
| Restricciones ineficaces reubicadas | pattern/format verificados en la aplicación |
Gestión de refusal |
El código distingue rechazo de error de esquema |
| Prueba con petición real | Respuesta de prueba validada antes del deploy |
Si quieres entender por qué additionalProperties: false es tan central, el análisis profundo de la palabra clave additionalProperties muestra cómo cada objeto abierto dilata el espacio de generación. Para integrar el esquema en un pipeline de CI con tests de contrato automáticos, el flujo descrito en JSON Schema contract testing cierra las regresiones silenciosas. Y si necesitas generar un esquema a partir de ejemplos JSON existentes, la herramienta de conversión a JSON Schema de la plataforma te hace partir de casos reales — aunque para el modo strict, igualmente tendrás que aplicar la reescritura descrita aquí.
FAQ
¿Por qué la documentación exige que todos los campos sean required, también los opcionales?
Porque el autómata de estados finitos debe decidir de antemano cuándo cada clave es legal. La "opcionalidad" se expresa con null, no con la ausencia de la clave: la unión nullable es la forma oficial de decirlo.
El esquema se acepta pero el pattern no funciona. ¿Es un bug?
No. En modo strict pattern, minLength, maximum y format no se aplican por la gramática de generación. El esquema es sintácticamente válido pero la restricción no existe: verifica en la aplicación.
¿Puedo usar $ref si también declaro $defs?
No, en ambos casos está prohibido. El esquema debe ser un único árbol, completamente expandido. Los scripts de reescritura automática se encargan de la expansión.
¿Cuál es la diferencia entre refusal y un error de esquema? El refusal es una respuesta conforme en la que el modelo declara semánticamente que no quiere ejecutar la tarea. Un error de esquema es un 400 al enviar o una salida no conforme. Son problemas distintos con remedios distintos.
¿Hasta qué profundidad puedo anidar objetos? Máximo 10 niveles de anidamiento y 5000 propiedades en total por esquema. Los esquemas generados automáticamente suelen superar estos límites: compruébalo antes de enviar.
Conclusión
El modo strict no es una opción cosmética: es el paso de "espero que el modelo respete el esquema" a "la gramática impide físicamente salidas no conformes". El precio es un subconjunto riguroso de JSON Schema — required completo, objetos cerrados, sin referencias — y algunas restricciones que pasan inadvertidas pero no se aplican. Invierte media hora en la reescritura con el script make_strict, marca las uniones nullable con criterio y prueba siempre con una petición real antes del deploy: el pipeline que resulta es cualitativamente distinto de uno construido sobre reintentos y correcciones a posteriori.