Pedir JSON no prompt devolve três sabores de dor: prosa em volta do objeto, aspas mal escapadas e valores de enum inventados. O parse quebra às 3h da manhã e quem está de plantão descobre depois. Structured outputs atacam a raiz: em vez de pedir e torcer, você restringe a geração token a token contra um JSON Schema.

Constrained decoding: validade durante a geração

Constrained decoding restringe a saída contra o schema no nível de cada token. O recurso de structured outputs da OpenAI e o tool use da Anthropic garantem validade sintática do primeiro ao último token. No mundo open-source, motores baseados em gramática como Outlines e as grammars do llama.cpp compilam o schema em máscaras de token e fazem o mesmo rodando na sua própria infraestrutura.

Regras de design de schema

  • Estrutura rasa ganha de aninhamento profundo; cada nível extra aumenta a chance de confusão
  • Enums vencem strings livres; modelo preenche campo ambíguo com valor plausível e errado
  • Campos obrigatórios explícitos e additionalProperties: false; modelos respeitam constraints melhor que instruções em texto

Validação continua sendo sua

Constrained decoding cobre a forma; semântica fica por sua conta. Data de checkout anterior à data de criação do pedido passa limpa pelo schema e explode no relatório contábil. Intervalos de data coerentes, integridade referencial e regras de negócio ficam fora do alcance do decoding. Uma camada de validação com zod, pydantic ou JSON Schema validators pega o que escapou, e os erros dela alimentam o retry.

Retry com o erro na mão

Falhou a validação? Reenvie o prompt incluindo a mensagem de erro do validador e a saída rejeitada, para o modelo ver o que corrigir. Um retry resolve a maioria dos casos; três falhas seguidas indicam prompt ou schema doentes e merecem rota de fallback ou fila humana. Sem esse limite, o loop de retry queima tokens em cima de um erro determinístico.

Versionamento de schemas

Adição de campos precisa manter compatibilidade retroativa: respostas em cache de semanas atrás têm de validar contra o parser novo. Adicione campos no fim do objeto, marque como opcionais e promova a obrigatórios depois; número de versão no envelope do payload ajuda a escalonar migração por coortes.

Teste as bordas do schema

Testes property-based geram prompts adversários que sondam limites: enums vazios, datas-limite, textos cheios de caracteres de escape. Entre com eles na suíte de evals, ao lado das métricas de qualidade; regressão de formato é regressão também.