Structured Outputs en 2026: Dejá de Parsear Esperanzas, Parseá Schemas

1. El Problema: JSON.parse No Es una Estrategia

Librado a su suerte, un LLM genera texto que parece JSON pero sin ninguna garantía. Un campo requerido ausente, un número devuelto como string, un valor de enum que nunca definiste, una clave extra que tu ORM rechaza — cualquiera de estas convierte una demo en un incidente. Insistir en el prompt (’devolvé SOLO JSON válido’) baja la tasa de fallos pero nunca la elimina, porque nada en el proceso de decodificación prohíbe realmente los tokens inválidos.

Los structured outputs lo resuelven en la capa de muestreo: con constrained decoding, el proveedor compila tu JSON Schema en una gramática y el modelo físicamente no puede emitir tokens que la violen. Cada clave requerida presente, cada tipo correcto, cada valor de enum de tu lista. Esa garantía — disponible en OpenAI, Anthropic y vía librerías como Vercel AI SDK e instructor — es de lo que trata este tutorial.

2. Conceptos Mínimos Antes de Tocar Código

Seis ideas cubren el 90% de lo que necesitás. Con esto claro, cada ejemplo de código de abajo se lee como castellano simple.

3. Paso 1 — Structured Outputs de OpenAI (Python + curl)

OpenAI expone structured outputs de dos formas equivalentes: declarar el JSON Schema crudo en response_format con strict: true, o pasarle al SDK un modelo de Pydantic y dejar que el helper parse derive el schema y devuelva un objeto tipado. Recomiendo la segunda — sin json.loads, sin validación manual, y los refusals aparecen como un campo de primera clase.

Python — parse tipado con Pydantic (recomendado)

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class SupportTicket(BaseModel):
    summary: str
    category: str
    severity: int
    account_id: str | None

completion = client.beta.chat.completions.parse(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "Extract the ticket into the schema."},
        {"role": "user", "content": "My checkout 500s with a saved card. Started today. Account: acct_8842."},
    ],
    response_format=SupportTicket,
)

ticket = completion.choices[0].message
if ticket.refusal:
    print("Refused:", ticket.refusal)
else:
    print(ticket.parsed)  # instancia de SupportTicket, garantizada por schema

¿Preferís HTTP crudo u otro lenguaje? La misma garantía está a un bloque response_format de distancia. Notá las tres reglas del strict mode dentro del schema: cada propiedad listada en required, additionalProperties en false, y enums explícitos. En los flagships más nuevos (la serie GPT-5 también soporta strict mode) la forma es idéntica — solo cambia el id del modelo, así que confirmá el soporte de strict en tu snapshot pineado en la documentación.

curl — Chat Completions con json_schema, strict true

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-2024-08-06",
    "messages": [
      {"role": "system", "content": "Extract the ticket into the schema."},
      {"role": "user", "content": "My checkout 500s with a saved card. Account: acct_8842."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"},
            "category": {"type": "string", "enum": ["billing", "bug", "account", "other"]},
            "severity": {"type": "integer"},
            "account_id": {"anyOf": [{"type": "string"}, {"type": "null"}]}
          },
          "required": ["summary", "category", "severity", "account_id"],
          "additionalProperties": false
        }
      }
    }
  }'

4. Paso 2 — generateText del Vercel AI SDK con Output + Zod

Si vivís en TypeScript, el Vercel AI SDK estandariza la generación estructurada entre proveedores vía generateText con un spec de output. Le pasás Output.object({ schema }) con tu schema de Zod, un prompt y un modelo; recibís un output totalmente tipado. El schema funciona también como validador, así que el tipo que ves en tu editor es la forma a la que el modelo fue constreñido. Nota: generateObject y streamObject están deprecados desde AI SDK 6 (PR #10754) y se eliminarán en una versión futura — generateText/streamText con Output es el reemplazo.

TypeScript — generateText con Output.object() y Zod

import { generateText, Output } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const { output } = await generateText({
  model: openai("gpt-4o-2024-08-06"),
  output: Output.object({
    schema: z.object({
      summary: z.string(),
      category: z.enum(["billing", "bug", "account", "other"]),
      severity: z.number(),
      accountId: z.string().nullable(),
    }),
  }),
  prompt: "Classify this ticket: My checkout 500s with a saved card. Account acct_8842.",
});

console.log(output.category); // tipado: "billing" | "bug" | "account" | "other"

Arrays y choices — misma función, spec de Output

// Array de objetos: element describe UN elemento
const { output: heroes } = await generateText({
  model: openai("gpt-4o-2024-08-06"),
  output: Output.array({
    element: z.object({ name: z.string(), description: z.string() }),
  }),
  prompt: "Generate 3 hero descriptions for a fantasy game.",
});

// Clasificacion: conjunto fijo de valores, sin schema
const { output: genre } = await generateText({
  model: openai("gpt-4o-2024-08-06"),
  output: Output.choice({
    options: ["action", "comedy", "drama", "horror", "sci-fi"],
  }),
  prompt: "Classify this plot: astronauts cross a wormhole seeking a new home.",
});

5. Paso 3 — Strict Tools de Anthropic + Instructor con Pydantic

Dos caminos más completan la caja de herramientas. En Anthropic, strict tool use (strict: true en la definición del tool) compila tu input_schema en una gramática, así el input del bloque tool_use tiene validez de schema garantizada y el nombre del tool es siempre uno que definiste. En Python en general, la librería instructor te da la misma experiencia tipada que el helper parse de OpenAI — pero uniforme en más de 15 proveedores, con reintentos automáticos ante fallos de validación.

Python — strict tool use de Anthropic

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "log_ticket",
        "description": "Log a classified support ticket.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
                "category": {"type": "string", "enum": ["billing", "bug", "account", "other"]},
                "severity": {"type": "integer"},
            },
            "required": ["summary", "category", "severity"],
            "additionalProperties": False,
        },
    }
]

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "My checkout 500s with a saved card. Log it as a bug."}],
)

for block in response.content:
    if block.type == "tool_use":
        print(block.name, block.input)  # input con validez de schema garantizada

Y cuando querés independencia del proveedor — el mismo código contra OpenAI, Anthropic, Gemini o un modelo local — from_provider de instructor es la capa más fina que igual te da objetos tipados. Definís un modelo de Pydantic, lo pasás como response_model, y recibís la instancia directamente, con max_retries cubriendo los casos donde la validación falla.

Python — instructor con Pydantic (cualquier proveedor)

import instructor
from pydantic import BaseModel

client = instructor.from_provider("openai/gpt-4o-mini")

class User(BaseModel):
    name: str
    age: int

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
    max_retries=3,
)

print(user)  # User(name="John", age=25), totalmente tipado

6. Una Rutina de Validación que Realmente Aguanta

Las garantías de schema eliminan una clase entera de bugs, pero no eliminan la disciplina de ingeniería. Esta es la rutina que corro en cada integración con structured outputs:

7. Errores Comunes (Todos Arreglables en Minutos)

Casi cada fallo de structured outputs que debuggueé cae en uno de estos baldes. La columna izquierda es lo que hacen las integraciones que funcionan; la derecha es lo que te despierta de noche.

Conclusión

Los structured outputs convierten la parte más frágil de las apps con LLMs — ’por favor devolvé JSON’ — en un contrato tipado impuesto en tiempo de generación. Viste el loop completo: response_format estricto en OpenAI con el helper parse, generateText con Output.object() y Zod en Vercel AI SDK, strict tool use en Anthropic, y extracción independiente del proveedor con instructor y Pydantic.

Elegí un camino esta semana y migrá un solo call site con JSON.parse: definí el schema, activá strict, agregá la rama de refusal y mantené un test de conformidad. Esa sola migración suele borrar más código de manejo de errores que cualquier otro cambio de su tamaño — y es la base sobre la que se va a parar cada agente, extractor y loop de tools que construyas después.

Fuentes

• OpenAI — Guía de Structured Outputs (response_format, strict mode, refusals)
• OpenAI — Presentación de Structured Outputs en la API
• Vercel AI SDK — Generación de datos estructurados (generateText, Output, Zod)
• Vercel AI SDK — Guía de migración 6.0 (deprecación de generateObject/streamObject, PR #10754)
• Anthropic — Strict tool use (input_schema con gramática restringida)
• Instructor — Structured outputs con OpenAI (from_provider, response_model)