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
| Construção | Exemplo | Notas |
|---|---|---|
| Tipos básicos | "type": "object", "array", "string", "integer", "number", "boolean", "null" | A base de todo esquema; combine livremente. |
enum | {"type": "string", "enum": ["baixo", "médio", "alto"]} | Restringe um campo a um conjunto fixo de valores - a ferramenta padrão para campos de estilo de classificação. |
const | {"const": "fatura"} | Fixa um campo em exatamente um valor literal. |
anyOf | {"anyOf": [{"type": "string"}, {"type": "integer"}]} | Permite que um campo corresponda a qualquer um de vários sub-esquemas. |
allOf | {"allOf": [{"$ref": "#/$defs/Base"}, {"properties": {...}}]} | Combina vários sub-esquemas que devem corresponder. |
$ref / $def | {"$ref": "#/$defs/Endereco"} | Composição/reutilização padrão de esquema - o que o Pydantic emite para modelos aninhados. |
format de String | date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid | Restringe a forma de uma string sem um regex personalizado. |
additionalProperties: false | {"type": "object", "additionalProperties": False} | Obrigatório em todo objeto no esquema, não opcional. |
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
| Construção | Exemplo (não será aplicado) | O que fazer em vez disso |
|---|---|---|
| Esquemas recursivos | Um objeto cujas propriedades se referem a si mesmo (direta ou via ciclos $ref) | Achate a forma, ou divida a extração em várias chamadas sequenciais. |
| Restrições de intervalo numérico | minimum, maximum, multipleOf | Valide o intervalo do número você mesmo após o parsing (um field_validator do Pydantic é um local natural para isso). |
| Restrições de comprimento de string | minLength, maxLength | Valide o comprimento da string você mesmo após o parsing. |
| Restrições complexas de array | e.g. minItems, maxItems, uniqueItems em combinação com outras palavras-chave de array | Valide a forma/comprimento do array você mesmo após o parsing. |
additionalProperties definido como qualquer coisa diferente de false | "additionalProperties": true ou um objeto de esquema | Sempre use additionalProperties: false - este é o único valor que a aplicação da API suporta. |
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 vTratamento do SDK de Restrições Não Suportadas
| SDK | Comportamento |
|---|---|
Python (anthropic) | Remove automaticamente restrições não suportadas do esquema antes de enviá-lo para a API, e então as valida no lado do cliente contra a resposta. |
TypeScript (@anthropic-ai/sdk) | Mesmo comportamento de remoção automática e validação no lado do cliente como o SDK Python. |
# 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
| Regra | Aplica-se a | Consequência se omitido |
|---|---|---|
required lista todas as propriedades que você precisa presentes | Todo objeto no esquema, incluindo os aninhados | Campos omitidos tornam-se opcionais; o modelo pode deixá-los de fora. |
additionalProperties: false | Todo objeto no esquema, incluindo os aninhados | O objeto fica aberto a campos extras não solicitados. |
| Aninhamento superficial (2-3 níveis) | O esquema como um todo | Estruturas profundas ou recursivas correm o risco de atingir território não suportado. |
Armadilhas
- Adicionar
minimum/maximume 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 umfield_validatordo Pydantic (ou equivalente) para verificar o intervalo após o parsing. - Definir
additionalPropertiespara um objeto de esquema para permitir "campos extras de um certo tipo." Apenas o literalfalseé suportado. Correção: se você precisar de campos extras flexíveis, modele-os explicitamente como uma propriedade conhecida (por exemplo, um objetometadata) em vez de depender deadditionalProperties. - 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,
childrencomo um tipo aninhado de profundidade fixa) ou represente a árvore como uma lista plana com referências pai em vez disso.
FAQs
O que acontece se eu usar minLength no meu esquema?
- Os SDKs Python e TypeScript o removem do esquema enviado para a API e, em vez disso, o validam no lado do cliente assim que a resposta chega.
- Não é aplicado pela restrição de tempo de geração da API - trate-o como uma verificação do lado do cliente, não uma garantia de tempo de geração.
Posso expressar "um de um conjunto fixo de strings" de forma suportada?
{"type": "string", "enum": ["rascunho", "enviado", "pago"]}- Sim -
enumé totalmente suportado e é a maneira padrão de restringir um campo a valores fixos.
additionalProperties é sempre obrigatório?
- Sim - todo objeto no esquema deve definir
additionalProperties: false. Não há valor suportado além defalse.
Posso aninhar objetos com três ou quatro níveis de profundidade?
- Dois a três níveis são confiáveis. Aninhamento muito profundo aumenta o risco de atingir uma construção não suportada ou um esquema que a API rejeita.
- Prefira achatar formas profundamente aninhadas onde os dados permitem.
Esquemas recursivos são rejeitados completamente, ou apenas não aplicados?
- Esquemas recursivos não são suportados para este recurso - evite uma propriedade que se refere ao seu próprio tipo contêiner, direta ou através de um ciclo
$ref.
$ref funciona como no JSON Schema padrão?
- Sim - a composição
$ref/$defé suportada, e é exatamente o quemodel_json_schema()do Pydantic gera para tiposBaseModelaninhados.
Posso validar intervalos numéricos de outra forma?
- Sim - como
minimum/maximum/multipleOfnão são aplicados, adicione umfield_validatordo Pydantic ou uma verificação manual apósclient.messages.parse()retornar.
Formatos de string como email e uuid são realmente aplicados?
- Sim - valores de
formatincluindoemail,uuid,date-time,date,time,duration,hostname,uri,ipv4eipv6são suportados.
Qual é o subconjunto mais seguro do JSON Schema para projetar?
- Tipos básicos,
enum,const,anyOf/allOf,$ref/$def, valores deformatde string suportados, maisrequiredeadditionalProperties: falseem todo objeto. - Qualquer coisa fora dessa lista deve ser tratada como não verificada até que você consulte esta página.
Uma restrição não suportada causa um erro na solicitação?
- Não necessariamente - os SDKs Python e TypeScript removem restrições não suportadas automaticamente em vez de gerar um erro, e então as validam no lado do cliente.
- Não confie em um erro para dizer que uma restrição não está funcionando; consulte esta referência em vez disso.
Arrays podem ter comprimentos restritos?
- Restrições complexas de array como
minItems/maxItems/uniqueItemsnão são suportadas. - Valide o comprimento ou a exclusividade do array você mesmo após a resposta chegar.
Relacionado
- Definindo um JSON Schema para output_config.format - as convenções
required/additionalPropertiesque 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
anthropicpara 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.