Referência de Tipos de Campo e Restrições de Saída Estruturada

Nem toda construção do JSON Schema é aplicada por output_config.format. Esta página é uma tabela de referência rápida para o que é suportado, o que não é, e o que acontece quando você usa uma construção não suportada de qualquer maneira.

Verifique isso antes de projetar um esquema com algo além de tipos básicos, enum e aninhamento simples.

Como Usar Esta Referência

• Escaneie a tabela "Suportado" primeiro ao projetar um novo esquema - atenha-se a essas construções para a garantia mais forte.
• Escaneie a tabela "Não Suportado" antes de adicionar uma restrição como um intervalo numérico ou limite de comprimento de string - ela não fará o que você espera.
• Quando uma construção não é suportada, use o tratamento do lado do cliente do SDK (abaixo) ou mova a restrição para sua própria etapa de pós-validação.
• Revisite esta página a qualquer momento que um esquema que você esperava ser aplicado não parecer estar se comportando conforme restrito.

Construções Suportadas

schema = {
    "type": "object",
    "properties": {
        "id": {"type": "string", "format": "uuid"},
        "status": {"type": "string", "enum": ["aberto", "fechado"]},
        "created_at": {"type": "string", "format": "date-time"},
    },
    "required": ["id", "status", "created_at"],
    "additionalProperties": False,
}

Não Suportado

from pydantic import BaseModel, field_validator
 
class Invoice(BaseModel):
    total: float
 
    @field_validator("total")
    @classmethod
    def total_in_range(cls, v: float) -> float:
        # O próprio esquema não pode impor este intervalo - faça isso aqui em vez disso.
        if not (0 <= v <= 1_000_000):
            raise ValueError("total fora do intervalo esperado")
        return v

Tratamento do SDK de Restrições Não Suportadas

# Você ainda pode escrever minLength em seu esquema para documentação/intenção -
# o SDK o remove antes que a solicitação seja enviada e o verifica no lado do cliente
# assim que a resposta retorna, em vez de ignorá-lo silenciosamente de ponta a ponta.
schema = {
    "type": "object",
    "properties": {"code": {"type": "string", "minLength": 4}},
    "required": ["code"],
    "additionalProperties": False,
}

Requisitos de Objeto em Resumo

Armadilhas

• Adicionar minimum/maximum e assumir que a API rejeita valores fora do intervalo. Ela não impõe isso - o campo será validado desde que seja do tipo numérico correto. Correção: adicione um field_validator do Pydantic (ou equivalente) para verificar o intervalo após o parsing.
• Definir additionalProperties para um objeto de esquema para permitir "campos extras de um certo tipo." Apenas o literal false é suportado. Correção: se você precisar de campos extras flexíveis, modele-os explicitamente como uma propriedade conhecida (por exemplo, um objeto metadata) em vez de depender de additionalProperties.
• Projetar um esquema auto-referencial para dados em árvore. Esquemas recursivos não são suportados. Correção: limite a profundidade explicitamente no esquema (por exemplo, children como um tipo aninhado de profundidade fixa) ou represente a árvore como uma lista plana com referências pai em vez disso.

FAQs

{"type": "string", "enum": ["rascunho", "enviado", "pago"]}

Relacionado

• Definindo um JSON Schema para output_config.format - as convenções required/additionalProperties que esta referência assume.
• Validando e Analisando Respostas Estruturadas em Python - onde a validação do lado do cliente de restrições não suportadas se encaixa em seu código.
• Lidando com Saída JSON Malformada ou Truncada - um modo de falha relacionado, mas separado, de construções de esquema não suportadas.

Versões da Stack: Escrito contra a linha de modelos Claude atual a partir de ~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.