Definición de un JSON Schema para output_config.format

output_config.format solo garantiza una respuesta válida según el schema si el schema que le proporcionas está bien formado.

Esta página cubre exactamente cómo escribir ese schema: los dos campos que cada objeto necesita, cómo construirlo manualmente frente a generarlo a partir de un modelo Pydantic, y cómo encajan el anidamiento, los arrays y los enums.

Resumen

El schema que pasas a output_config.format es un JSON Schema estándar, con dos convenciones que la API de Claude requiere en cada objeto: un array required que lista cada propiedad, y additionalProperties: false.

Acertar con estos dos en cada objeto anidado es la fuente más común de errores de schema.

Puedes escribir el schema como un diccionario Python plano, o generarlo automáticamente a partir de un BaseModel de Pydantic con .model_json_schema().

Ambos enfoques producen el mismo formato de transmisión; Pydantic simplemente te ahorra tener que mantener un diccionario y un tipo analizado sincronizados manualmente.

No todas las palabras clave de JSON Schema son compatibles, por lo que un schema que parece razonable aún puede ser rechazado o ignorado silenciosamente en algunas partes; consulta la referencia de tipos de campo y restricciones para ver la lista completa.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

from anthropic import Anthropic
 
client = Anthropic()
 
schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "priority": {"type": "string", "enum": ["low", "medium", "high"]},
    },
    "required": ["title", "priority"],
    "additionalProperties": False,
}
 
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": schema}},
    messages=[{"role": "user", "content": "Resume este informe de error como un ticket."}],
)

Cuándo usar esto:

• Cualquier vez que el código posterior analice la respuesta de Claude como datos en lugar de mostrarla como texto.
• Extrayendo un conjunto fijo de campos de una entrada no estructurada (correos electrónicos, tickets, texto de formularios).
• Tareas de clasificación donde la respuesta debe ser una de un conjunto conocido de etiquetas.
• Siempre que actualmente confíes en la redacción del prompt "por favor, devuelve solo JSON".

Ejemplo de Trabajo

from pydantic import BaseModel, Field
from anthropic import Anthropic
 
class BugReport(BaseModel):
    title: str = Field(description="Un resumen corto y de una línea del error")
    priority: str = Field(description="Uno de: low, medium, high")
    steps_to_reproduce: list[str] = Field(description="Lista ordenada de pasos de reproducción")
    affected_component: str
 
client = Anthropic()
 
response = client.messages.parse(
    model="claude-sonnet-5",
    max_tokens=1024,
    output_config={
        "format": {"type": "json_schema", "schema": BugReport.model_json_schema()}
    },
    messages=[{
        "role": "user",
        "content": (
            "Convierte esto en un informe de error: La página de pago falla cuando un usuario "
            "aplica un código de descuento con caracteres especiales. Ocurre cada vez "
            "en el módulo de pagos. Inicia sesión, añade un artículo al carrito, aplica un código como "
            "'SAVE#10', haz clic en pagar. Esto bloquea todas las compras, por lo que es de alta prioridad."
        ),
    }],
)
 
report: BugReport = response.parsed_output
print(report.title)
print(report.priority)
for step in report.steps_to_reproduce:
    print("-", step)

Lo que esto demuestra:

• Field(description=...) en un modelo Pydantic se convierte en la description del JSON Schema que el modelo lee al decidir qué poner en cada campo.
• list[str] se convierte automáticamente en un array de elementos string; no se necesita un schema de array manual.
• response.parsed_output devuelve una instancia real de BugReport, no un diccionario, por lo que el acceso a atributos y los verificadores de tipos funcionan.
• El schema y el tipo en tiempo de ejecución se definen exactamente una vez, en una sola clase.

Inmersión Profunda

Cómo Funciona

• output_config.format toma un envoltorio type: "json_schema" alrededor de tu objeto schema; el schema en sí es un documento JSON Schema estándar.
• La API restringe la generación de tokens para que la respuesta solo pueda ser texto que valide contra el schema que proporcionaste; no está validando después del hecho, está restringiendo durante la generación.
• required le dice a la API que cada propiedad listada debe estar presente en la respuesta; omitir una propiedad de required la hace opcional, lo cual rara vez es lo que quieres para una tarea de extracción fija.
• additionalProperties: false cierra el objeto; sin él, la API (y cualquier validador estricto que superpongas) no puede garantizar que el modelo no agregará campos adicionales no solicitados.
• Tanto required como additionalProperties: false se necesitan en cada objeto del schema, incluidos los objetos anidados; establecerlos solo en el nivel superior no se propaga hacia abajo.

Construcción del Schema Manualmente vs. con Pydantic

Los schemas escritos a mano son útiles para formas muy simples y únicas, o cuando no quieres una dependencia de Pydantic. Para cualquier cosa con más de dos o tres campos, un modelo Pydantic evita que el schema y el tipo de datos de tu aplicación se separen a medida que la forma evoluciona.

Objetos Anidados y Arrays

from pydantic import BaseModel
 
class LineItem(BaseModel):
    sku: str
    quantity: int
 
class Order(BaseModel):
    customer_name: str
    items: list[LineItem]
 
# Order.model_json_schema() produce un objeto de nivel superior con una propiedad de array "items"
# cuya palabra clave "items" apunta al schema del objeto LineItem anidado;
# cada nivel aún necesita su propio required + additionalProperties: false, que
# Pydantic genera automáticamente para ti.

• El anidamiento es compatible a través de la composición ordinaria de JSON Schema (properties, items, $ref/$def), que es exactamente lo que Pydantic emite para modelos anidados.
• Mantén el anidamiento superficial. Dos o tres niveles de profundidad son confiables; las estructuras muy profundas o recursivas no son compatibles; consulta la referencia de tipos de campo.
• Cada objeto en cada nivel todavía necesita su propia lista required y additionalProperties: false; Pydantic maneja esto correctamente por sí solo, pero si escribes schemas anidados a mano, agrega ambos a cada objeto anidado tú mismo.

Notas de Python

from pydantic import BaseModel
 
class Ticket(BaseModel):
    subject: str
    urgency: str
 
schema = Ticket.model_json_schema()
print(schema["required"])            # ['subject', 'urgency']
print(schema["additionalProperties"])  # False

• model_json_schema() de Pydantic establece required y additionalProperties: false automáticamente para un BaseModel estándar sin campos opcionales; esta es una razón para preferirlo sobre escribir el diccionario a mano.
• Un campo tipado como Optional[str] o al que se le asigna un valor predeterminado se excluye de required por Pydantic; si deseas que todos los campos sean obligatorios en la respuesta, evita los valores predeterminados y Optional en los campos que importan.
• response.parsed_output de client.messages.parse(...) está tipado como una instancia del modelo que pasaste, por lo que los IDE y los verificadores de tipos entienden la forma sin anotaciones adicionales.

Parámetros y Valores de Retorno

Trampas Comunes

• Olvidar additionalProperties: false en un objeto anidado. Establecerlo solo en el nivel superior deja los objetos internos abiertos. Solución: verifica que cada objeto anidado en el schema también lleve additionalProperties: false; si escribes schemas a mano, es fácil pasarlo por alto en un campo profundamente anidado.
• Listar un campo en properties pero no en required. El campo se vuelve opcional, por lo que el modelo puede omitirlo y tu código debe verificar defensivamente su presencia. Solución: incluye cada campo que realmente necesitas en required, y solo haz que los campos sean opcionales cuando la respuesta genuinamente pueda no tenerlos.
• Asumir que cada palabra clave de JSON Schema funciona. Cosas como las restricciones de rango numérico o ciertas palabras clave de composición complejas no son aplicadas por la API. Solución: consulta la referencia de tipos de campo y restricciones antes de diseñar un schema más allá de los tipos básicos, enum y anidamiento simple.
• Reutilizar un modelo Pydantic con campos Optional para una tarea de extracción "debe tener todo". Los campos opcionales/con valor predeterminado se eliminan automáticamente de required, lo que debilita la garantía que realmente querías. Solución: mantén los campos no opcionales sin valor predeterminado cuando cada valor deba estar presente en la respuesta.
• Tratar una respuesta válida según el schema como datos garantizados correctos. El schema impone la forma, no la precisión; un campo priority: "high" aún puede ser válido según el schema y ser factualmente incorrecto. Solución: mantén tu propio paso de validación o revisión posterior para la corrección, independientemente de la conformidad del schema.
• Escribir un schema excesivamente profundo o recursivo. Los schemas recursivos (un objeto que se referencia a sí mismo) no son compatibles, y el anidamiento muy profundo aumenta la posibilidad de que se introduzca una construcción no compatible. Solución: aplana la forma siempre que sea posible, o divide una extracción profundamente anidada en dos llamadas secuenciales.

Alternativas

Preguntas Frecuentes

{"type": "string", "enum": ["low", "medium", "high"]}

{
    "type": "object",
    "properties": {"answer": {"type": "string"}},
    "required": ["answer"],
    "additionalProperties": False,
}

Relacionados

• Conceptos Básicos de Salidas Estructuradas - solicita una respuesta de JSON schema y analízala con client.messages.parse.
• Validación y Análisis de Respuestas Estructuradas en Python - qué sucede con este schema una vez que solicitas una respuesta con él.
• Referencia de Tipos de Campo y Restricciones de Salida Estructurada - la lista completa de construcciones de schema compatibles e incompatibles referenciadas en toda esta página.
• Manejo de Salidas JSON Malformadas o Truncadas - qué hacer cuando un schema bien formado aún regresa incompleto.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.