JSON Toolkit

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.

Intermediário~8 min de leituraPublicado em 2026-11-19Atualizado em 2026-11-19
Diagrama das regras de reescrita de JSON Schema para o modo strict de LLMs

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:

  1. 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.
  2. 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.
  3. 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 refusal da 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.

Referências

Artigos relacionados

Testes de contrato JSON Schema: solde as regras de validação na CI

Um schema não termina quando é escrito — é ali que começa a degradação. Um erro de digitação afrouxa a validação em silêncio, uma refatoração quebra todas as fixtures. Este guia apresenta uma arquitetura viável de teste de contrato: fixtures positivos, negativos e de snapshot, lint do próprio schema, compilação única reutilizada e quatro portões de CI que transformam quebra de contrato em build vermelho.

Intermediário~8 min de leituraAtualizado em 2026-11-05

O JSON do LLM veio truncado: olhe o motivo de parada antes de falar em reparo

O modelo devolve um JSON que termina no meio do valor e o parser só informa uma coluna. Fechar as chaves faz voltar a analisar, mas cada campo faltante fica escondido nos dados. O artigo traça a fronteira entre o que um reparo de truncamento pode recuperar com honestidade e o que precisa ser reenviado: gate por stop_reason, dimensionamento do limite e ordem dos campos do schema.

Prático~5 min de leituraAtualizado em 2026-11-14

Sem additionalProperties, a validação de schema não valida nada

Validação bem-sucedida não significa dados limpos. O Pydantic ignora campos desconhecidos por padrão, o Zod os remove e o Ajv deixa passar — parâmetros alucinados e chaves com erro de digitação atravessam em silêncio. Este artigo mostra as três formas de aceitação silenciosa e dá receitas completas: fechar objetos, controlar coerção e apertar cada nível de aninhamento.

Intermediate~8 min de leituraAtualizado em 2026-11-02