JSON Schema

Structured Outputs

Cuando trabajas con modelos LLM como gpt-5 o gpt-5.1, lo habitual es recibir respuestas en texto libre, difíciles de procesar automáticamente en una aplicación. Las Structured Outputs permiten pedir al modelo que responda en formato JSON estructurado, con una forma concreta y estable definida de antemano.

En lugar de interpretar párrafos de texto, tu backend recibe directamente un objeto JSON con claves y tipos bien definidos (cadenas, números, booleanos, listas), lo que simplifica validaciones, mapeos a DTOs y almacenamiento en bases de datos. El modelo se ajusta a esa estructura utilizando un JSON Schema que le indica exactamente qué campos puede generar.

Ejemplo conceptual de salida libre vs JSON

Imagina que pides al modelo que resuma un artículo sobre FastAPI. Una salida en texto libre podría ser:

FastAPI es un framework web para Python enfocado en rendimiento y tipado.
Permite crear APIs rápidamente, con validación automática y documentación integrada.

La misma información como JSON estructurado podría verse así:

{
  "titulo": "Introducción a FastAPI",
  "resumen_corto": "Framework web para construir APIs en Python con alto rendimiento.",
  "palabras_clave": ["Python", "API", "FastAPI"]
}

En el segundo caso, tu aplicación puede acceder de forma directa a titulo, resumen_corto o palabras_clave sin necesidad de hacer parsing frágil de texto. Esta es la idea central de las Structured Outputs: transformar la creatividad del modelo en datos estructurados fiables.

• 1. Menos lógica de postprocesado: reduces código de parsing y normalización en el backend, porque la estructura del JSON ya viene acordada.
• 2. Respuestas más previsibles: el modelo sabe qué campos debe rellenar y qué tipo de dato debe usar en cada uno, lo que mejora la consistencia entre peticiones.
• 3. Integración más sencilla: es más fácil conectar un LLM con sistemas existentes (formularios, APIs internas, bases de datos) cuando trabajas siempre con objetos JSON bien definidos.

Qué es JSON Schema

Un documento JSON es simplemente una estructura de datos con objetos, listas y valores primitivos (cadenas, números, booleanos). Sin embargo, por sí solo no indica qué forma debería tener el JSON correcto en un determinado contexto de negocio.

JSON Schema es una especificación que permite describir la forma esperada de un JSON: qué propiedades existen, qué tipo tiene cada una, cuáles son obligatorias y qué valores son válidos. Funciona como un contrato entre tu aplicación y los datos que produce el modelo.

De forma muy simplificada, los elementos básicos de un JSON Schema son:

• 1. type: indica el tipo principal del valor ("object", "array", "string", "integer", "boolean", etc.), lo que permite describir si esperas un objeto, una lista o un valor simple.
• 2. properties: define las claves permitidas dentro de un objeto, asociando a cada una un subesquema con su propio type y restricciones, lo que documenta la estructura completa.
• 3. required: lista de propiedades que deben estar presentes siempre en el JSON de salida, garantizando que el modelo no omita información crítica.
• 4. additionalProperties: indica si se permiten claves extra no definidas en properties; establecerlo a false ayuda a mantener una estructura estricta y fácil de consumir.

Un ejemplo de JSON Schema sencillo para describir el resumen de un recurso educativo podría ser:

{
  "type": "object",
  "properties": {
    "titulo": { "type": "string" },
    "nivel": {
      "type": "string",
      "enum": ["basico", "intermedio", "avanzado"]
    },
    "duracion_minutos": { "type": "integer" },
    "publicado": { "type": "boolean" }
  },
  "required": ["titulo", "nivel", "duracion_minutos"],
  "additionalProperties": false
}

Este esquema indica que el JSON debe ser un objeto con las propiedades titulo, nivel, duracion_minutos y publicado, donde algunas son obligatorias y los valores admitidos para nivel están acotados mediante enum. Esta misma estructura será la que reutilices después al configurar las Structured Outputs en la API de OpenAI.

Uso en Chat Completions

Si ya trabajas con la API de Chat Completions, puedes seguir usando el mismo flujo de messages, añadiendo el parámetro response_format para activar las Structured Outputs con JSON Schema. El modelo seguirá recibiendo mensajes de sistema y de usuario, pero la respuesta se ajustará a la estructura que definas.

El primer paso es definir el esquema que describe la salida esperada. Por ejemplo, un resumen de artículo con título, resumen y lista de palabras clave:

articulo_schema = {
    "type": "object",
    "properties": {
        "titulo": {"type": "string"},
        "resumen_corto": {"type": "string"},
        "palabras_clave": {
            "type": "array",
            "items": {"type": "string"}
        }
    },
    "required": ["titulo", "resumen_corto", "palabras_clave"],
    "additionalProperties": False,
}

Después, se envía una petición de Chat Completions indicando ese esquema en response_format:

from openai import OpenAI
import json

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.1",
    messages=[
        {
            "role": "system",
            "content": "Resumes artículos y devuelves siempre un JSON que cumple el esquema indicado.",
        },
        {
            "role": "user",
            "content": "Resume un artículo introductorio sobre FastAPI y sugiere 3 palabras clave.",
        },
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "resumen_articulo",
            "schema": articulo_schema,
            "strict": True,
        },
    },
)

json_str = completion.choices[0].message.content
resultado = json.loads(json_str)

En este ejemplo, el modelo gpt-5.1 genera directamente un JSON que cumple el esquema articulo_schema. La clave name identifica el esquema a efectos de trazabilidad, mientras que strict: True indica al modelo que debe respetarlo de manera estricta. Desde tu código de Python, solo necesitas aplicar json.loads para obtener un diccionario listo para usar en tu lógica de negocio.

Uso en Responses

La API de Responses está diseñada para trabajar de forma especialmente cómoda con Structured Outputs, ya que expone directamente la salida ya parseada según el esquema que definas. En lugar de procesar texto, accedes a una estructura de datos que la propia API ha validado contra tu JSON Schema.

Partiendo de un esquema similar al anterior, puedes configurar una llamada a client.responses.create de la siguiente manera:

from openai import OpenAI

client = OpenAI()

curso_schema = {
    "type": "object",
    "properties": {
        "titulo": {"type": "string"},
        "descripcion": {"type": "string"},
        "nivel": {
            "type": "string",
            "enum": ["basico", "intermedio", "avanzado"]
        },
        "duracion_minutos": {"type": "integer"}
    },
    "required": ["titulo", "descripcion", "nivel", "duracion_minutos"],
    "additionalProperties": False,
}

response = client.responses.create(
    model="gpt-5-nano",
    input="Propón un curso breve de introducción a FastAPI para principiantes.",
    text={
        "format": {
            "type": "json_schema",
            "name": "resumen_curso",
            "schema": curso_schema,
            "strict": True,
        }
    },
)
print(response.output_text)

# Para acceder a sus atributos como un diccionario:
content_json = json.loads(response.output_text)
print(content_json["titulo"])  

Una alternativa a manejar manualmente JSON Schema y los resultados JSON es usar Pydantic, ya que Chat Completions y Responses admiten utilizar directamente schemas Pydantic.