JSON Toolkit

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.

Intermedio~8 min de lecturaPublicado el 2026-11-19Actualizado el 2026-11-19
Diagrama de reglas de reescritura de JSON Schema para el modo strict de LLM

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.

Referencias

Artículos relacionados

Tests de contrato con JSON Schema: soldar las reglas de validación en CI

Un esquema no termina cuando se escribe — ahí es donde empieza a degradarse. Una errata relaja la validación en silencio, una refactorización rompe todos los fixtures. Esta guía disecciona un sistema de tests de contrato que se puede ejecutar: fixtures positivos, negativos y de snapshot, lint del propio esquema, compilación única con reutilización y cuatro gates de CI que convierten los cambios que rompen contratos en builds rojos.

Intermedio~8 min de lecturaActualizado el 2026-11-05

El JSON de un LLM llegó truncado: mira el motivo de parada antes de hablar de reparación

El modelo devuelve un JSON que termina a mitad de un valor y el parser solo ofrece un número de columna. Cerrar las llaves lo hace analizable otra vez, pero cada campo ausente queda escondido dentro de los datos. Este artículo traza la frontera entre lo que una reparación de truncado puede recuperar con honestidad y lo que debe reintentarse: control por stop_reason, dimensionado del límite y orden de los campos del esquema.

Práctico~5 min de lecturaActualizado el 2026-11-14

Sin additionalProperties, la validación de esquema no valida nada

Una validación exitosa no significa datos limpios. Pydantic ignora los campos desconocidos por defecto, Zod los elimina y Ajv los deja pasar — los parámetros alucinados y las claves mal escritas atraviesan en silencio. Este artículo muestra las tres formas de aceptación silenciosa y da recetas completas: cerrar objetos, controlar la coerción y apretar cada nivel de anidación.

Intermediate~8 min de lecturaActualizado el 2026-11-02