Ir al contenido principal
Español— Elegir un idioma
Menú

Modo JSON y aplicación de esquemas

Lección 10 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Modo JSON y aplicación de esquemas
  2. Modo JSON frente a Salida Estructurada
  3. Salida Estructurada con esquema JSON
  4. Reglas para la Salida Estructurada estricta
  5. Ayudante para construir esquemas
  6. Ejemplo: extracción de datos estructurados
  7. Medir lo que aporta la restricción
  8. Puntos clave

Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI: temperature y top_p solo se aceptan con un esfuerzo de razonamiento de none, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificar reasoning={"effort": "none"} (API de Responses) o reasoning_effort="none" (Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.

Modo JSON y aplicación de esquemas

La Salida Estructurada (Structured Output) de OpenAI garantiza que la respuesta del modelo sea un JSON válido que se ajuste a un esquema definido por ti. Se acabó el análisis frágil con expresiones regulares o los errores de formato: la restricción se aplica directamente en el nivel de generación.

Este matiz es crítico y lo cambia todo para un desarrollador. Pedir «responde en JSON» en el prompt es una súplica: el modelo obedece la mayoría de las veces, pero un día prefija su respuesta con «Aquí tienes el JSON solicitado:», añade comillas invertidas de Markdown u olvida una coma, y tu json.loads lanza una excepción en producción a las 3 de la mañana durante el lote más grande de la semana. Con la Salida Estructurada, la restricción se aplica durante la decodificación: simplemente no se pueden elegir tokens que produzcan un JSON inválido o no conforme. Dejas de suplicar y empiezas a hacer cumplir.

Modo JSON frente a Salida Estructurada

OpenAI ofrece dos niveles de restricción, y la distinción depende de una sola palabra. El Modo JSON garantiza un JSON válido sin restricciones estructurales; la Salida Estructurada garantiza un JSON conforme a un esquema JSON que hayas escrito.

El Modo JSON resuelve la mitad del problema. Tienes la seguridad de poder analizar la respuesta, pero no de qué contendrá: el modelo podría nombrar un campo annee en una solicitud y year en la siguiente, o envolver su lista en un objeto resultats que no usó el día anterior. Para un prototipo o una visualización en bruto destinada a un humano, esto basta; en cuanto la salida alimenta código que accede a campos por nombre, necesitas el segundo nivel.

from openai import OpenAI

client = OpenAI()

# Modo JSON simple (JSON válido, estructura libre)
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="Always respond in JSON.",
    input="List 3 programming languages with their year of creation.",
    text={"format": {"type": "json_object"}}
)

import json
data = json.loads(response.output_text)
print(data)

Salida Estructurada con esquema JSON

Esta es la función más potente. Defines un esquema JSON y la API garantiza que la salida se ajuste a él. El ejemplo siguiente analiza el sentimiento de una reseña de cliente e ilustra tres usos complementarios del esquema.

El enum en sentiment evita que el modelo invente una categoría intermedia como «bastante positivo»: debe elegir entre los cuatro valores proporcionados, lo que hace que la salida sea directamente utilizable en un filtro o panel de control. La description del campo score actúa como un mini-prompt local, indicando la escala esperada sin necesidad de explicarla en las instrucciones generales, y permanece adjunta al campo aunque el prompt evolucione. Por último, el array aspects permite descomponer una reseña contradictoria —aquí, un producto gustado pero una entrega fallida— en lugar de aplastar ese matiz en una única puntuación que no sirve a nadie.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analyze the sentiment of: 'The product is excellent "
          "but the delivery was catastrophic.'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "schema": {
                "type": "object",
                "properties": {
                    "sentiment": {
                        "type": "string",
                        "enum": ["positive", "negative", "mixed", "neutral"]
                    },
                    "score": {
                        "type": "number",
                        "description": "Score from -1.0 (very negative) to 1.0 (very positive)"
                    },
                    "aspects": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "aspect": {"type": "string"},
                                "sentiment": {
                                    "type": "string",
                                    "enum": ["positive", "negative", "neutral"]
                                }
                            },
                            "required": ["aspect", "sentiment"],
                            "additionalProperties": False
                        }
                    },
                    "summary": {"type": "string"}
                },
                "required": ["sentiment", "score", "aspects", "summary"],
                "additionalProperties": False
            },
            "strict": True
        }
    }
)

result = json.loads(response.output_text)
# Garantizado: result tiene exactamente los campos definidos
print(f"Sentiment: {result['sentiment']}")
print(f"Score: {result['score']}")
for aspect in result["aspects"]:
    print(f"  - {aspect['aspect']}: {aspect['sentiment']}")

Reglas para la Salida Estructurada estricta

El modo strict: true impone sus propias restricciones al esquema. Todos los campos deben aparecer en required, y additionalProperties debe ser false en cada objeto. Los tipos permitidos son string, number, integer, boolean, array, object y null, además de enum para restringir valores. Sin embargo, ni pattern ni minLength/maxLength son aceptados: la validación detallada ocurre del lado del cliente.

Estas reglas pueden resultar sorprendentes en el primer intento porque prohíben el campo opcional tal como se escribe habitualmente en JSON Schema. La contrapartida es cómoda: tu código nunca tiene que comprobar si existe una clave; siempre está ahí. Para un campo que legítimamente puede estar vacío —un número de teléfono faltante en un documento, una fecha de fin para un contrato en curso—, la respuesta no es eliminarlo de required, sino permitir que sea null. En cuanto a la ausencia de pattern y límites de longitud, señala la siguiente lección: el esquema garantiza la forma, pero la validación de negocio sigue siendo tu tarea una vez recibida la respuesta.

Ayudante para construir esquemas

Escribir manualmente el bloque text.format para cada llamada se vuelve rápidamente tedioso y propenso a errores tipográficos: falta una clave name, un strict mal colocado y el error regresa desde la API sin indicar dónde buscar. Unas pocas líneas de código envoltorio centralizan la estructura, aplican una temperatura baja por defecto (ya que la variabilidad no aporta nada a la extracción) y hacen legible el punto de llamada.

def structured_query(prompt: str, schema: dict,
                     schema_name: str = "response",
                     model: str = "gpt-5.6-terra",
                     system: str = "") -> dict:
    """Envoltorio para solicitudes de Salida Estructurada."""
    response = client.responses.create(
        model=model,
        reasoning={"effort": "none"},  # temperature requiere effort none
        instructions=system or "Respond in JSON according to the provided schema.",
        input=prompt,
        text={
            "format": {
                "type": "json_schema",
                "name": schema_name,
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.1
    )
    return json.loads(response.output_text)

Ejemplo: extracción de datos estructurados

Este es el caso de uso que por sí solo justifica aprender esta técnica: transformar una factura recibida como texto plano en un objeto utilizable por tu sistema de contabilidad. El esquema describe tres niveles: la cabecera de la factura, un objeto anidado vendor y un array lines donde cada elemento tiene la misma forma. El modelo debe, por tanto, localizar información dispersa por todo el documento y colocarla en el sitio correcto, incluso para una línea expresada en horas en lugar de unidades, donde el precio unitario se entiende como tarifa horaria.

Ten en cuenta que los totales aparecen en el esquema como campos a extraer, no a recalcular. Pedimos al modelo que lea; el control aritmético ocurre después en tu código, donde una simple comparación entre la suma de las líneas y el total_ht extraído señalará los documentos para revisión humana.

invoice_schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "date": {"type": "string"},
        "vendor": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "siret": {"type": "string"},
                "address": {"type": "string"}
            },
            "required": ["name", "siret", "address"],
            "additionalProperties": False
        },
        "lines": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "integer"},
                    "unit_price_excl_tax": {"type": "number"},
                    "vat_percent": {"type": "number"}
                },
                "required": ["description", "quantity",
                             "unit_price_excl_tax", "vat_percent"],
                "additionalProperties": False
            }
        },
        "total_excl_tax": {"type": "number"},
        "total_incl_tax": {"type": "number"}
    },
    "required": ["invoice_number", "date", "vendor",
                  "lines", "total_excl_tax", "total_incl_tax"],
    "additionalProperties": False
}

invoice_text = """
Invoice No. 2026-0042
Date: 15/03/2026
Vendor: TechServ SARL, SIRET 123 456 789 00012
12 rue de la Paix, 75002 Paris

- REST API Development x1: 3500.00 EUR excl. tax (VAT 20%)
- Cloud hosting (3 months) x1: 450.00 EUR excl. tax (VAT 20%)
- Technical support x10h: 150.00 EUR excl. tax/h (VAT 20%)

Total excl. tax: 5450.00 EUR
Total incl. tax: 6540.00 EUR
"""

result = structured_query(
    invoice_text,
    invoice_schema,
    schema_name="invoice",
    system="Extract the data from this invoice."
)

Medir lo que aporta la restricción

Aplica este principio a un documento que conozcas bien: define un esquema JSON para extraer información clave de un currículum —nombre, experiencia, habilidades, educación— y pruébalo con tres currículums en texto plano elegidos deliberadamente por sus maquetaciones heterogéneas. Verifica que la salida respete el esquema incluso cuando falte completamente una sección.

A continuación, repite la misma extracción sin Salida Estructurada, pidiendo simplemente JSON en el prompt, y mantén las seis salidas una al lado de la otra. Comparar las dos series muestra lo que aporta la restricción: la diferencia rara vez reside en el contenido extraído, casi siempre en la estabilidad de los nombres de los campos y la presencia de las claves esperadas.

Puntos clave

  • La Salida Estructurada garantiza un JSON conforme al esquema en el nivel de generación
  • Usa strict: true para el máximo cumplimiento
  • Todos los campos deben ser required con additionalProperties: false
  • Ideal para extracción de datos, clasificación y tuberías de procesamiento
  • La validación detallada (longitud, patrón) ocurre del lado del cliente tras la recepción