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

Salida estructurada: JSON garantizado

Lección 9 de 22 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Salida estructurada: JSON garantizado
  2. El problema que resuelve
  3. Pydantic en lugar de escribir JSON Schema a mano
  4. Dos casos de uso comunes
  5. Qué exige el modo estricto
  6. Puntos clave

Salida estructurada: JSON garantizado

La salida estructurada es una de las funcionalidades más potentes de la API de Responses. En lugar de confiar en que el modelo devuelva un JSON válido, lo garantizas proporcionando un esquema. De este modo, el modelo queda estructuralmente restringido a seguirlo. Esto transforma un modelo de lenguaje, pasando de ser un generador de texto creativo a convertirse en un componente fiable de una cadena de procesamiento automatizada.

El problema que resuelve

Solicitar JSON en el prompt funciona la mayoría de las veces, y precisamente eso es lo que hace peligroso este enfoque. Un día de cada cien, el modelo precede su respuesta con una frase introductoria, envuelve todo en un bloque de código Markdown o renombra un campo; como resultado, tu json.loads() lanza una excepción en producción ante una solicitud que no puedes reproducir.

from openai import OpenAI
client = OpenAI()

# Sin estructura: el modelo puede devolver cualquier formato
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Dame información sobre París en JSON."
)
print(response.output_text)
# Resultado impredecible:
# A veces JSON válido, a veces texto que contiene JSON,
# a veces un formato inesperado...

El parámetro text cambia la naturaleza de la garantía. Declaras un formato json_schema junto con el esquema esperado, y la salida se ajusta a él: la deserialización se convierte en una operación segura.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Dame información sobre París.",
    text={
        "format": {
            "type": "json_schema",
            "name": "city_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "country": {"type": "string"},
                    "population": {"type": "integer"},
                    "official_language": {"type": "string"},
                    "landmarks": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "country", "population", "official_language", "landmarks"],
                "additionalProperties": False
            }
        }
    }
)

import json
data = json.loads(response.output_text)
print(f"Ciudad: {data['name']}")
print(f"Población: {data['population']:,}")
print(f"Lugares de interés: {', '.join(data['landmarks'])}")

# Resultado GARANTIZADO de ser JSON válido:
# Ciudad: París
# Población: 2.161.000
# Lugares de interés: Torre Eiffel, Louvre, Notre-Dame, Arco del Triunfo, Sacré-Cœur

Pydantic en lugar de escribir JSON Schema a mano

Escribir esquemas a mano se vuelve rápidamente tedioso y propenso a errores tipográficos. Pydantic te permite describirlos como clases de Python, generar el JSON Schema con model_json_schema() y, a continuación, validar y tipar la respuesta con model_validate_json(). Al final de la cadena, obtienes un objeto Python completo con autocompletado en el editor, en lugar de un diccionario anónimo.

from pydantic import BaseModel
from typing import Optional
import json

class Product(BaseModel):
    name: str
    price: float
    category: str
    in_stock: bool
    description: Optional[str] = None

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Describe un portátil gaming de gama alta.",
    text={
        "format": {
            "type": "json_schema",
            "name": "product",
            "strict": True,
            "schema": Product.model_json_schema()
        }
    }
)

# Analizar y validar con Pydantic
product = Product.model_validate_json(response.output_text)
print(f"Producto: {product.name}")
print(f"Precio: {product.price} EUR")
print(f"En stock: {'Sí' if product.in_stock else 'No'}")

# Resultado:
# Producto: ASUS ROG Strix G18
# Precio: 2499,99 EUR
# En stock: Sí

Nada te limita a estructuras planas. Mediante la composición de clases, puedes describir objetos anidados y listas de objetos, algo que necesitarás en cuanto crees un perfil de cliente realista: una empresa contiene contactos y cada contacto tiene una dirección.

from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    last_name: str
    first_name: str
    email: str
    phone: str
    address: Address

class Company(BaseModel):
    name: str
    sector: str
    employees: int
    contacts: list[Contact]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Genera un perfil de empresa ficticia del sector tecnológico "
          "con 2 contactos.",
    text={
        "format": {
            "type": "json_schema",
            "name": "company",
            "strict": True,
            "schema": Company.model_json_schema()
        }
    }
)

company = Company.model_validate_json(response.output_text)
print(f"Empresa: {company.name} ({company.sector})")
for c in company.contacts:
    print(f"  - {c.first_name} {c.last_name}: {c.email}")

Dos casos de uso comunes

El primero es la extracción: convertir texto escrito en un registro utilizable. Un anuncio de conferencia redactado en lenguaje natural se transforma en una fila de base de datos con título, fecha, ubicación y número de asistentes, sin necesidad de expresiones regulares y sin romperse cada vez que cambia la redacción.

class Event(BaseModel):
    title: str
    date: str
    location: str
    attendees: int

text = """
La conferencia PyCon France 2026 se celebrará los días 15 y 16 de noviembre
en el Palais des Congrès de Lyon. Se espera que más de 800 desarrolladores
de Python asistan a esta edición.
"""

response = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Extrae la información de este evento:\n{text}",
    text={
        "format": {
            "type": "json_schema",
            "name": "event",
            "strict": True,
            "schema": Event.model_json_schema()
        }
    }
)

evt = Event.model_validate_json(response.output_text)
print(f"{evt.title} - {evt.date} en {evt.location} ({evt.attendees} asistentes)")
# Resultado: PyCon France 2026 - 15-16 de noviembre de 2026 en Lyon (800 asistentes)

El segundo es la clasificación. Al declarar una enumeración, restringes el modelo a un vocabulario cerrado: no puede responder «más bien positivo» o «positivo» cuando tu código espera positive. Esta es la diferencia entre un valor que puedes usar directamente y un valor que debes normalizar después.

from enum import Enum

class Sentiment(str, Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"

class Analysis(BaseModel):
    sentiment: Sentiment
    confidence: float
    keywords: list[str]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Analiza este comentario: 'Gran servicio, entrega rápida!'",
    text={
        "format": {
            "type": "json_schema",
            "name": "sentiment_analysis",
            "strict": True,
            "schema": Analysis.model_json_schema()
        }
    }
)

analysis = Analysis.model_validate_json(response.output_text)
print(f"Sentimiento: {analysis.sentiment.value} ({analysis.confidence:.0%})")
# Resultado: Sentimiento: positive (95 %)

Qué exige el modo estricto

La garantía conlleva una contrapartida: cuando strict: True, el esquema debe adherirse a un subconjunto específico de JSON Schema. Estas restricciones son la causa principal de los errores 400 para los principiantes, así que es mejor conocerlas antes de encontrártelas:

  • Todas las propiedades deben listarse en required
  • additionalProperties debe ser False
  • Tipos admitidos: string, number, integer, boolean, array, object, null
  • No se permite oneOf ni anyOf con tipos mezclados
  • Usa Optional[str], que se traduce a {"anyOf": [{"type": "string"}, {"type": "null"}]}

La regla sobre required suele sorprender: un campo opcional no se expresa eliminándolo de la lista, sino permitiendo el valor null, exactamente lo que produce Optional[str] en el lado de Pydantic.

Puntos clave

  • La salida estructurada garantiza que la respuesta se ajuste a tu esquema JSON
  • Usa text={"format": {"type": "json_schema", ...}} en la API de Responses
  • Pydantic es la herramienta ideal para definir y validar esquemas
  • Activa strict: True para garantizar el cumplimiento del esquema
  • Ideal para extracción de datos, clasificación y generación estructurada