Saídas estruturadas de LLM que quebram: como escrever de verdade um schema para o modo strict
Resumo: Ativar strict num JSON Schema comum costuma devolver 400: todos os campos em required, additionalProperties:false em cada objeto, $ref e allOf rejeitados de cara. Este guia mostra como reescrever em lote um schema frouxo para uma versão compatível com strict, com uniões nullable, limites rígidos e checklist de triagem de refusals.

Resumo: strict: true não é um interruptor de "sejamos um pouco mais sérios" — é um contrato que aceita apenas um subconjunto do JSON Schema. Todos os campos em required, additionalProperties: false em cada objeto, $ref e allOf rejeitados de imediato. Enviar um schema não reescrito em modo strict dá um 400, não uma saída mais confiável.
O mesmo schema que passa lisinho no seu validador local volta na hora que você anexa strict: true e envia para a API do modelo. O modelo não ficou mais burro — o fornecedor traçou uma fronteira rígida em torno do subconjunto de schema que a decodificação restrita precisa, e o seu schema cruzou essa linha.
O que o strict muda de verdade: trancar o amostrador numa gramática
No modo comum, o JSON gerado pelo modelo só provavelmente casa com o seu schema, sustentado pela linha "responda em JSON" no prompt. Nos evals oficiais da OpenAI, a gpt-4-0613 seguindo schemas complexos só com prompt ficava abaixo de 40%; com o strict ligado, a gpt-4o-2024-08-06 atingiu 100% na mesma suíte.
O mecanismo é a decodificação restrita (constrained decoding): no primeiro pedido, a API compila seu schema num autômato de estados finitos e, durante a decodificação, cada token precisa ser liberado por esse autômato. O modelo não consegue emitir um token que viole o schema. Não é um lembrete — é um cadeado físico. O preço vem em duas parcelas: a primeira compilação de um schema novo leva tempo extra (normalmente menos de 10 segundos, até um minuto nos complexos) e soma cerca de 5-8% de latência no primeiro token; os artefatos compilados ficam em cache e os pedidos seguintes não pagam nada.
Deixe claro o que é garantido e o que não é: sintaxe e forma ficam trancadas, a semântica não. O modelo ainda pode preencher estimate_hours com 400 com toda a confiança ou extrair o e-mail errado. Forma é piso, não teto — a qualidade semântica continua dependendo de um conjunto de evals. Em 2026, mesmo os modelos de ponta sob carga mostram cerca de 0,4% de taxa residual de malformação; o loop de retentativas continua obrigatório.
Três regras duras: tudo required, nada de chaves extras, nullable no lugar de optional
O modo strict impõe três exigências de reescrita, e cada uma vai contra a intuição comum do JSON Schema:
- Todo campo precisa entrar no required. O modo strict não conhece o conceito de campo opcional. Para expressar "opcional", mantenha o campo no required mas declare o tipo como união nullable —
"type": ["string", "null"]— e deixe o modelo devolver null quando ausente. É o oposto exato da prática padrão, em que o required lista só os campos realmente necessários. - Cada objeto precisa declarar explicitamente additionalProperties: false. Em schemas comuns costuma-se deixar isso de lado (veja nosso artigo sobre o comportamento do additionalProperties nos runtimes), mas no modo strict é condição de admissão: sem ele, o pedido cai. O motivo é direto — o autômato só gera chaves declaradas, qualquer chave não declarada é inalcançável por construção.
- A armadilha do Python: o Pydantic derruba campos com default do required. Um
priority: str = "low"remove uma entrada do required do schema gerado, e o strict o rejeita. Remova o default ou complete em lote com o script abaixo.
As três regras precisam se aplicar recursivamente a cada objeto aninhado. Corrigir só o topo e deixar os objetos filhos intactos também produz um 400. Exemplo mínimo conforme:
{
"type": "object",
"properties": {
"intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
"note": { "type": ["string", "null"] }
},
"required": ["intent", "note"],
"additionalProperties": false
}
Essas escrituras caem de cara: palavras-chave proibidas e palavras-chave mudas
O modo strict suporta apenas um subconjunto do JSON Schema. Separe as palavras-chave em dois baldes e trate-os de formas diferentes:
| Balde | Palavras-chave | Comportamento no modo strict |
|---|---|---|
| Rejeitado de imediato | referências $ref / $defs, allOf, not, dependentRequired, dependentSchemas, if/then/else |
A API devolve erro; o pedido falha |
| Silenciosamente não aplicado | pattern, minLength, maxLength, format, minimum, maximum, multipleOf (modelos fine-tuned) |
Nem erro nem aplicação — restrições regex para revalidar na camada da aplicação |
O tratamento difere: o primeiro balde precisa ser reescrito — desdobre os $ref inline e mescle o allOf em properties. O segundo pode ficar (algumas configurações os aceitam), mas nunca o trate como defesa. Contar com "pattern": "^v\\d+\\.\\d+\\.\\d+$" para garantir o formato de versão é correr nu sob strict; rode uma validação explícita em cada resposta. Mais uma regra lá em cima: a raiz do schema não pode ser array nem união nua — embrulhe num object.
Limites rígidos: 5.000 propriedades, 10 níveis de aninhamento, 120.000 caracteres
Mesmo com todas as palavras-chave conformes, estourar os limites de tamanho derruba. Os números oficiais da OpenAI:
- no máximo 5.000 propriedades de objeto no schema inteiro, no máximo 10 níveis de aninhamento (na Anthropic o teto é de cerca de 6 níveis);
- comprimento total das strings de nomes de propriedades, nomes de definições, valores de enum e const limitado a 120.000 caracteres;
- no máximo 1.000 valores de enum no total; um enum de strings com mais de 250 valores não pode passar de 15.000 caracteres.
Raramente se bate nessas marcas, mas "tomar o dicionário inteiro da empresa como enum" e "comprimir um grafo de objetos de três níveis em um só" são dois cenários reais de acidente. Ao encontrar, divida: quebre o schema gigante em várias chamadas ou achate a estrutura. Bônus útil: as chaves de saída seguem a ordem das chaves do schema; parsers de jusante que dependem de ordem fixa podem tratar isso como recurso.
Um script que reescreve em lote um schema frouxo na forma strict
Editar à mão camada por camada convida a faltas. O script recursivo abaixo (o padrão publicado no guia 2026 do DevToolLab) completa "cada objeto fechado, cada chave required" numa passada:
def make_strict(schema: dict) -> dict:
"""additionalProperties:false + cada chave required, em todos os níveis."""
if isinstance(schema, dict):
if schema.get("type") == "object" and "properties" in schema:
schema["additionalProperties"] = False
schema["required"] = list(schema["properties"].keys())
for value in schema["properties"].values():
make_strict(value)
elif isinstance(schema, dict):
for value in schema.values():
make_strict(value)
elif isinstance(schema, list):
for item in schema:
make_strict(item)
return schema
O fluxo de trabalho companheiro: primeiro infira um esqueleto de schema a partir de um JSON de amostra (a página de ferramenta /convert/schema deste site faz inferência unidirecional de JSON para Schema), use o esqueleto como ponto de partida, aperte com as três regras strict e passe o make_strict como última rede de segurança. Atenção: o script conserta só a forma — uniões nullable, enums e campos semânticos seguem sendo decisões humanas; qualquer schema com $ref precisa ser desdobrado inline antes de entrar no script.
O equivalente na Anthropic: tool-as-schema
A Anthropic não tem um interruptor strict: true. O padrão canônico de 2026 é anexar o schema da resposta como input_schema de uma ferramenta e forçar o modelo a chamá-la via tool_choice:
await anthropic.messages.create({
model: "claude-sonnet-4-6",
tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
tool_choice: { type: "tool", name: "emit" },
messages,
});
O canal de chamada de ferramentas valida o JSON por si só, então o efeito equivale ao modo strict. As diferenças moram nos detalhes: teto de aninhamento da Anthropic de cerca de 6 níveis, suporte a .nullable() em vez de .optional(); os três fornecedores (OpenAI, Anthropic, Gemini) aceitam subconjuntos de schema levemente diferentes. Reusar um mesmo schema sem mudanças entre fornecedores não é confiável — revalide a cada troca de modelo.
Triagem de refusal, truncamento e timeouts antes de falar de retentativas
Quando o modo strict entrega algo inválido, só há três causas, e cada uma pede reação diferente:
- Refusal: o modelo recusou executar (pedido inseguro etc.). O campo
refusalda resposta é verdadeiro — ler JSON nesse momento não faz sentido; passe para humano ou reescreva o pedido. - Truncamento:
finish_reasonélength— o max_tokens não bastou, a saída está fisicamente incompleta. Restrições de schema não salvam saída truncada; aumente o orçamento ou comprima a estrutura. Identificação e recuperação parcial no nosso artigo sobre diagnóstico e reparo de JSON truncado. - Malformação: quando o fornecedor não suporta o subconjunto por completo, JSON ruim ainda pode chegar. Não retente só com "tente de novo" — devolva o texto exato do erro de validação ao prompt: "severity deve ser low/medium/high/critical; você emitiu urgent; corrija e emita de novo". Retentativas com contexto de erro derrubam a média de retentativas de 3 para cerca de 1,5.
Coloque um teto duro de retentativas (duas, digamos); acima disso, degrade para um modelo menor de correção ou para uma fila humana. Não deixe uma única saída ruim estrangular o pipeline inteiro.
Checklist antes de subir
| Verificação | Critério de passagem |
|---|---|
| required | Cada campo de cada objeto está no required |
| additionalProperties | false explícito em cada objeto, até o nível mais profundo |
| Semântica opcional | Modelada com uniões ["string", "null"]; sem optional nu |
| Palavras-chave proibidas | Sem $ref / allOf / if-then-else / dependentRequired |
| Palavras-chave mudas | pattern e format revalidados na camada da aplicação |
| Tamanho | ≤5.000 propriedades, ≤10 níveis, ≤120.000 caracteres de string |
| Triagem | refusal / length / erro de parse tratados por caminhos separados |
| Retentativas | Com o texto original do erro, teto de 2, depois degradação |
| Semântica | Evals ou asserções de campo fora do schema |
Passada a checklist, a confiabilidade da forma está efetivamente trancada. Para semântica e evolução de contrato — versionar schemas e fazer um schema quebrado deixá-lo vermelho primeiro no CI — veja soldando contratos de schema no CI.
FAQ
O modo strict garante valores corretos dos campos?
Não. Ele tranca só sintaxe e forma na decodificação: cada chave presente, tipos corretos, enums legais. Nada sobre correção semântica — o modelo ainda pode produzir dados bem formados mas errados. A camada semântica depende de evals ou asserções por campo.
Por que campos opcionais também entram no required?
O autômato do modo strict exige que cada propriedade declarada seja alcançável; uma entrada required omitida cai na validação. A opcionalidade é simulada com a união ["string", "null"]: o campo sempre aparece, o valor pode ser null, e o código de jusante trata null como ausência.
pattern e minLength são totalmente inúteis?
Sob modelos fine-tuned e na maioria das configurações strict não são aplicados. Não dão erro — e é isso que os torna perigosos: você acha que tem defesa, e não tem. Valide explicitamente com ajv ou jsonschema as respostas que dependem dessas restrições.
O modo strict deixa as respostas mais lentas?
Só o primeiro pedido com schema novo paga a compilação (normalmente menos de 10 segundos, até um minuto nos complexos). Depois que os artefatos compilados vão para o cache, os pedidos seguintes veem só cerca de 5-8% de latência extra no primeiro token. Em regime estável é imperceptível; o custo real aparece só com schemas que mudam com frequência.
O que retestar depois de trocar a versão do modelo?
Três coisas: se o subconjunto de schema suportado mudou nessa versão, se os campos refusal e finish_reason continuam lá, se os limites de aninhamento e tamanho se apertaram. Fornecedores aceitam subconjuntos diferentes; antes de reusar um schema entre modelos, verifique com um pedido mínimo.