Salida estructurada: JSON garantizado
En esta página
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 additionalPropertiesdebe serFalse- Tipos admitidos:
string,number,integer,boolean,array,object,null - No se permite
oneOfnianyOfcon 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: Truepara garantizar el cumplimiento del esquema - Ideal para extracción de datos, clasificación y generación estructurada