Definindo um JSON Schema para output_config.format

output_config.format só garante uma resposta válida em termos de schema se o schema que você fornece estiver bem formado.

Esta página cobre exatamente como escrever esse schema: os dois campos que todo objeto precisa, como construí-lo manualmente versus gerá-lo a partir de um modelo Pydantic, e como aninhamento, arrays e enums se encaixam.

Resumo

O schema que você passa para output_config.format é um JSON Schema padrão, com duas convenções que a API Claude exige em cada objeto: um array required listando cada propriedade e additionalProperties: false.

Acertar esses dois em cada objeto aninhado é a fonte mais comum de erros de schema.

Você pode escrever o schema como um dicionário Python simples ou gerá-lo automaticamente a partir de um BaseModel Pydantic com .model_json_schema().

Ambas as abordagens produzem o mesmo formato de comunicação; Pydantic apenas economiza o trabalho de manter um dicionário e um tipo analisado em sincronia manualmente.

Nem toda palavra-chave JSON Schema é suportada, então um schema que parece razoável ainda pode ser rejeitado ou ignorado silenciosamente em algumas partes - veja a referência de tipos de campo e restrições para a lista completa.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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": "Resuma este relatório de bug como um ticket."}],
)

Quando usar isso:

• Qualquer vez que o código downstream for analisar a resposta do Claude como dados em vez de exibi-la como texto.
• Extrair um conjunto fixo de campos de entrada não estruturada (e-mails, tickets, texto de formulário).
• Tarefas de classificação onde a resposta deve ser um de um conjunto conhecido de rótulos.
• Sempre que você estiver contando com a instrução "por favor, retorne apenas JSON" na sua prompt.

Exemplo de Trabalho

from pydantic import BaseModel, Field
from anthropic import Anthropic
 
class BugReport(BaseModel):
    title: str = Field(description="Um resumo curto e de uma linha do bug")
    priority: str = Field(description="Um de: low, medium, high")
    steps_to_reproduce: list[str] = Field(description="Lista ordenada de passos para reproduzir")
    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": (
            "Transforme isto em um relatório de bug: A página de checkout falha quando um usuário "
            "aplica um código de desconto com caracteres especiais. Acontece sempre "
            "no módulo de pagamentos. Faça login, adicione um item ao carrinho, aplique um código como "
            "'SAVE#10', clique em checkout. Isso bloqueia todas as compras, então é alta prioridade."
        ),
    }],
)
 
report: BugReport = response.parsed_output
print(report.title)
print(report.priority)
for step in report.steps_to_reproduce:
    print("-", step)

O que isso demonstra:

• Field(description=...) em um modelo Pydantic se torna a description do JSON Schema que o modelo lê ao decidir o que colocar em cada campo.
• list[str] se torna automaticamente um array de itens string - nenhum schema de array manual é necessário.
• response.parsed_output retorna uma instância real de BugReport, não um dicionário, então o acesso a atributos e verificadores de tipo funcionam.
• O schema e o tipo de tempo de execução são definidos exatamente uma vez, em uma única classe.

Análise Profunda

Como Funciona

• output_config.format recebe um wrapper type: "json_schema" em torno do seu objeto schema; o schema em si é um documento JSON Schema padrão.
• A API restringe a geração de tokens para que a resposta só possa ser texto que valide contra o schema que você forneceu - ela não valida depois do fato, ela restringe durante a geração.
• required informa à API que cada propriedade listada deve estar presente na resposta; omitir uma propriedade de required a torna opcional, o que raramente é o que você quer para uma extração fixa.
• additionalProperties: false fecha o objeto - sem ele, a API (e qualquer validador rigoroso que você adicione por cima) não pode garantir que o modelo não adicionará campos extras e não solicitados.
• Tanto required quanto additionalProperties: false são necessários em todo objeto do schema, incluindo objetos aninhados - defini-los apenas no nível superior não se aplica em cascata.

Construindo o Schema Manualmente vs. com Pydantic

Schemas escritos à mão são úteis para formas muito simples e únicas, ou quando você não quer uma dependência Pydantic. Para qualquer coisa com mais de dois ou três campos, um modelo Pydantic mantém o schema e o tipo de dados da sua aplicação de se separarem à medida que a forma evolui.

Objetos Aninhados e 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() produz um objeto de nível superior com uma propriedade de array "items"
# onde a palavra-chave "items" aponta para o schema do objeto LineItem aninhado -
# cada nível ainda precisa de seu próprio required + additionalProperties: false, que
# Pydantic gera automaticamente para você.

• O aninhamento é suportado através da composição comum do JSON Schema (properties, items, $ref/$def), que é exatamente o que Pydantic emite para modelos aninhados.
• Mantenha o aninhamento raso. Dois ou três níveis de profundidade são confiáveis; estruturas muito profundas ou recursivas não são suportadas - veja a referência de tipos de campo.
• Todo objeto em cada nível ainda precisa de sua própria lista required e additionalProperties: false; Pydantic lida com isso corretamente por conta própria, mas se você escrever schemas aninhados manualmente, adicione ambos a cada objeto aninhado você mesmo.

Notas 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() do Pydantic define required e additionalProperties: false automaticamente para um BaseModel padrão sem campos opcionais - esta é uma razão para preferi-lo a escrever o dicionário manualmente.
• Um campo tipado como Optional[str] ou com um valor padrão é excluído de required pelo Pydantic - se você quiser que todos os campos sejam obrigatórios na resposta, evite padrões e Optional em campos que importam.
• response.parsed_output de client.messages.parse(...) é tipado como uma instância do modelo que você passou, então IDEs e verificadores de tipo entendem a forma sem anotação extra.

Parâmetros e Valores de Retorno

Armadilhas

• Esquecer additionalProperties: false em um objeto aninhado. Definir isso apenas no nível superior deixa os objetos internos abertos. Correção: verifique se todo objeto aninhado no schema também carrega additionalProperties: false - se você estiver escrevendo schemas manualmente, é fácil esquecer isso em um campo profundamente aninhado.
• Listar um campo em properties mas não em required. O campo se torna opcional, então o modelo pode omiti-lo, e seu código precisa verificar defensivamente sua presença. Correção: inclua todo campo que você realmente precisa em required, e torne os campos opcionais apenas quando a resposta genuinamente pode não tê-los.
• Assumir que toda palavra-chave JSON Schema funciona. Coisas como restrições de intervalo numérico ou certas palavras-chave de composição complexas não são aplicadas pela API. Correção: verifique a referência de tipos de campo e restrições antes de projetar um schema além de tipos básicos, enum e aninhamento simples.
• Reutilizar um modelo Pydantic com campos Optional para uma tarefa de extração "precisa ter tudo". Campos opcionais/com valor padrão saem de required automaticamente, o que enfraquece a garantia que você realmente queria. Correção: mantenha os campos não opcionais sem padrão quando todos os valores devem estar presentes na resposta.
• Tratar uma resposta válida em termos de schema como dados garantidos corretos. O schema impõe a forma, não a precisão - um campo priority: "high" ainda pode ser válido em termos de schema e factualmente incorreto. Correção: mantenha sua própria validação ou etapa de revisão para correção, independente da conformidade do schema.
• Escrever um schema excessivamente profundo ou recursivo. Schemas recursivos (um objeto referenciando a si mesmo) não são suportados, e aninhamento muito profundo aumenta a chance de um construto não suportado se infiltrar. Correção: achate a forma sempre que possível, ou divida uma extração profundamente aninhada em duas chamadas sequenciais.

Alternativas

FAQs

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

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

Relacionados

• Noções Básicas de Saídas Estruturadas - solicite uma resposta de schema JSON e analise-a com client.messages.parse.
• Validando e Analisando Respostas Estruturadas em Python - o que acontece com este schema depois que você solicita uma resposta com ele.
• Referência de Tipos de Campo e Restrições de Saída Estruturada - a lista completa de construtos de schema suportados e não suportados referenciados nesta página.
• Lidando com Saída JSON Malformada ou Truncada - o que fazer quando um schema bem formado ainda volta incompleto.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.