🔍 TL;DR
O modo JSON impõe a sintaxe JSON, não a conformidade com o esquema — campos ausentes, tipos incorretos e valores de enum inválidos exigem correções no prompt. Três técnicas fecham essa lacuna: (1) incorporar o esquema como template JSON diretamente no prompt, (2) incluir um exemplo de saída válida, (3) adicionar uma instrução por campo cobrindo tipo, formato e tratamento de null. Mire em 95%+ de taxa de aprovação em um conjunto de teste de 20 casos antes do deploy. Use YAML em vez de JSON para prompts de formato livre sem enforcement de API — os modelos produzem menos erros de sintaxe.
O design do prompt determina a confiabilidade da saída estruturada
📍 In One Sentence
Confiabilidade de saída estruturada é o percentual de respostas do modelo que são analisáveis, contêm todos os campos obrigatórios, usam tipos de dados corretos e têm valores de enum válidos — o modo JSON garante apenas o primeiro desses quatro.
💬 In Plain Terms
Pense no modo JSON como o corretor ortográfico: ele detecta erros de sintaxe, mas não erros de significado. Um prompt que depende apenas do modo JSON é como um documento que passou pelo corretor — estruturalmente válido, mas potencialmente incompleto ou com tipos incorretos.
APIs de modo JSON e tool_use impõem JSON analisável, mas não garantem a completude dos campos, tipos de dados corretos ou valores de enum válidos — essas falhas exigem correções a nível de prompt, não mudanças na API. As falhas mais comuns em saída estruturada ocorrem dentro de JSON sintaticamente válido: campos obrigatórios ausentes porque o modelo os tratou como opcionais, datas formatadas como strings relativas em vez de ISO 8601, valores de enum com erros de digitação ou abreviados, e campos anuláveis retornando strings vazias em vez de null.
Três intervenções a nível de prompt fecham consistentemente a lacuna de confiabilidade. A incorporação do esquema torna a estrutura de saída inequívoca. Um único exemplo de saída válida remove a ambiguidade de formato. Instruções por campo eliminam erros de tipo e de tratamento de null. Juntas, essas três elevam a confiabilidade da saída estruturada para 95%+ no GPT-5.5, Claude 4.6 Sonnet e Gemini 2.5 Pro — com ou sem modo JSON nativo.
| Tipo de falha | O que a causa no prompt | Correção no prompt |
|---|---|---|
| Campo obrigatório ausente | O modelo infere que o campo é opcional a partir da descrição em linguagem natural | Rotule cada campo obrigatório explicitamente: "title REQUIRED" ou liste os campos obrigatórios separadamente |
| Tipo de dado incorreto | Nome de campo ambíguo sem anotação de tipo | Adicione anotação de tipo no prompt: "amount (integer, not string)" |
| Valor de enum inválido | Enum não listado por completo — o modelo inventa um valor plausível | Liste todos os valores de enum explicitamente: "status: one of 'active', 'inactive', 'pending'" |
| Confusão null vs string vazia | Sem instrução distinguindo null de "" | Adicione: "Return null if unknown. Never return empty string for unknown values." |
| Campos extras não declarados | O modelo adiciona contexto útil não incluído no esquema | Adicione: "Return only the fields specified. Do not add fields not listed in the schema." |
Incorporar o esquema diretamente no prompt
Incorpore o esquema de saída esperado como template JSON diretamente no prompt, não como descrição em linguagem natural. Modelos que veem a estrutura antes de gerá-la produzem menos omissões de campos e erros de tipo do que modelos que recebem apenas uma descrição em prosa do que você quer.
Um esquema no prompt usa o formato exato que você espera na saída: nomes de campos, profundidade de aninhamento e placeholders de valores. Coloque o template do esquema após sua instrução de tarefa e antes de qualquer exemplo. Use valores de placeholder que comuniquem o tipo esperado: `"amount": 0` comunica integer; `"amount": 0.00` comunica float; `"created_at": "YYYY-MM-DDTHH:MM:SSZ"` comunica o formato ISO 8601 esperado.
❌ Apenas descrição em linguagem natural
Extraia os detalhes do pedido do seguinte texto e retorne-os como JSON. Inclua o ID do pedido, o nome do cliente, o valor total, os itens pedidos e o status do pedido. Texto: {{text}}
✅ Esquema incorporado como template JSON
Extraia os detalhes do pedido do seguinte texto e retorne-os como JSON que corresponda exatamente a este esquema: { "order_id": "string", "customer_name": "string", "total_amount": 0.00, "status": "string", "items": [ { "name": "string", "quantity": 0, "unit_price": 0.00 } ] } Retorne apenas JSON válido. Não inclua nenhum texto fora do objeto JSON. Texto: {{text}}
Mostrar ao modelo um exemplo de saída válida
Adicionar um exemplo de saída concreto e realista ao prompt eleva a confiabilidade da saída estruturada em 5–8 pontos percentuais em comparação com prompts que têm apenas o esquema. O exemplo mostra ao modelo o formato exato, a ordem dos campos, o estilo dos valores e a convenção de aspas que você espera — reduzindo a ambiguidade que a definição do esquema sozinha não consegue eliminar.
Coloque o exemplo após o template do esquema e rotule-o claramente ("Exemplo de saída:" ou "Aqui está uma resposta válida:"). Use valores de placeholder realistas — não "foo", "bar" ou "exemplo" — porque os modelos aprendem com o estilo dos valores.
❌ Apenas esquema — sem exemplo de saída
Extraia os detalhes do produto da avaliação abaixo e retorne JSON com este esquema: { "product_name": "string", "rating": 0, "sentiment": "string", "key_features": ["string"] } Avaliação: {{review}}
✅ Esquema + um exemplo de saída realista
Extraia os detalhes do produto da avaliação abaixo e retorne JSON com este esquema: { "product_name": "string", "rating": 0, "sentiment": "string", "key_features": ["string"] } Exemplo de saída: { "product_name": "Headphones WH-1000XM5", "rating": 4, "sentiment": "positive", "key_features": ["cancelamento de ruído", "bateria de 30 horas", "ajuste confortável"] } Avaliação: {{review}}
Escrever instruções por campo para saída de alto risco
Para prompts de produção onde a correção dos campos é crítica, adicione uma instrução por campo obrigatório: o tipo de dado, o formato esperado, o tratamento de null e os valores de enum permitidos quando aplicável. As instruções por campo eliminam a ambiguidade que causa erros de tipo.
As instruções de campo ficam em uma seção separada após o template do esquema, antes do exemplo. Rotule a seção "Requisitos de campo:" ou "Regras do esquema:". Mantenha cada instrução em uma frase.
| Tipo de campo | Padrão de instrução | Instrução de exemplo |
|---|---|---|
| String | Formato, comprimento máximo, caracteres não permitidos | "title (string, máx 100 caracteres, sem tags HTML)" |
| Number | Integer vs float, precisão, unidades | "price (float, exatamente 2 casas decimais, USD, sem símbolo de moeda)" |
| Date | Formato, fuso horário | "created_at (string, ISO 8601: YYYY-MM-DDTHH:MM:SSZ, fuso horário UTC)" |
| Enum | Todos os valores permitidos listados literalmente | "status (string, exatamente um de: 'active', 'inactive', 'pending')" |
| Boolean | apenas true/false — rejeitar yes/no/1/0 | "is_verified (boolean, apenas true ou false — não 1/0 nem yes/no)" |
| Nullable | Quando retornar null vs string vazia vs omitir | "description (string ou null — retorne null se desconhecido, string vazia apenas se souber que está em branco)" |
| Array | Mín/máx de itens, tipo do item, tratamento de array vazio | "tags (array de strings, 0–5 itens, retorne [] se nenhum — nunca retorne null)" |
❌ Apenas esquema — sem instruções de campo
Retorne JSON com estes campos: { "invoice_id": ..., "amount": ..., "due_date": ..., "status": ..., "line_items": [...] }
✅ Esquema + instruções por campo
Retorne JSON com estes campos: { "invoice_id": "string", "amount": 0.00, "due_date": "YYYY-MM-DD", "status": "string", "line_items": [{"description": "string", "quantity": 0, "unit_price": 0.00}] } Requisitos de campo: - invoice_id: string, formato INV-XXXXXX (ex.: INV-004821) - amount: float, 2 casas decimais, total em USD incluindo impostos - due_date: string, data ISO 8601 (YYYY-MM-DD), não um datetime - status: string, exatamente um de: 'paid', 'unpaid', 'overdue', 'cancelled' - line_items: array de objetos, 1 ou mais itens, retorne [] se nenhuma linha encontrada - Se qualquer campo não puder ser determinado, retorne null para esse campo
Escolha JSON para APIs, YAML para prompts, CSV para dados tabulares
Use JSON quando a saída alimenta uma API ou banco de dados com enforcement de JSON disponível. Use YAML para prompts de formato livre sem enforcement de API — os modelos produzem menos erros de sintaxe em YAML porque não requer chaves de fechamento, sequências de escape nem atenção a vírgulas finais. Use CSV apenas para dados tabulares planos.
A diferença de confiabilidade entre JSON e YAML em prompting de formato livre (sem enforcement de API) decorre da complexidade da sintaxe. JSON exige que cada string seja entre aspas, cada objeto seja fechado com uma chave e cada vírgula esteja correta. YAML usa recuo — que os modelos gerenciam de forma mais consistente.
- Use JSON se o seu sistema posterior tem um analisador JSON e o enforcement de API está disponível — o enforcement elimina erros de sintaxe por completo
- Use YAML se você está gerando sem enforcement de API e sua equipe converte para JSON antes do processamento posterior
- Use CSV apenas para dados tabulares planos — no momento em que você precisar de um objeto aninhado ou um array em uma célula, mude para JSON ou YAML
- Use tabelas Markdown apenas para saída legível por humanos — elas não são analisáveis por máquinas sem ferramentas adicionais
| Formato | Confiabilidade sem enforcement de API | Melhor para | Evite quando |
|---|---|---|---|
| JSON | 80–85% com esquema no prompt | APIs, bancos de dados, consumidores com tipo seguro | Não há enforcement de API e há aninhamento complexo envolvido |
| YAML | 88–92% com esquema no prompt | Saída legível por humanos, dados estilo configuração, sem enforcement de API | O sistema posterior requer JSON sem uma etapa de conversão |
| XML | 85–90% com esquema no prompt | Transformação de documentos, integração com sistemas legados | Dados simples de chave-valor (XML adiciona verbosidade desnecessária) |
| CSV | 95%+ para dados planos | Dados tabulares, exportações para planilhas, pipelines de dados | Os dados têm estrutura aninhada ou hierárquica |
| Tabelas Markdown | Alta para tabelas simples | Relatórios, documentação, saída tabular legível por humanos | Processamento posterior legível por máquinas é necessário |
Pedir ao modelo que corrija sua própria saída malformada
Quando um prompt de saída estruturada falha na validação, envie um prompt de correção contendo a instrução original, a saída malformada e o erro de validação específico. Os modelos recuperam saída válida de suas próprias respostas malformadas em 60–75% dos casos sem reescrever o prompt por completo.
Um prompt de correção tem três partes obrigatórias: (1) uma reafirmação de como a saída deve ser (o esquema ou formato), (2) a saída malformada exatamente como o modelo a retornou, e (3) o erro de validação específico — "campo obrigatório 'invoice_id' ausente", "amount é uma string, esperava-se float".
❌ Nova tentativa vaga — sem contexto de erro
Você retornou uma saída inválida. Por favor, tente novamente e retorne JSON válido. {{original_prompt}}
✅ Prompt de correção com esquema, saída e erros específicos
Sua resposta anterior falhou na validação. Corrija apenas os erros listados abaixo e retorne o JSON corrigido. Esquema esperado: { "invoice_id": "string", "amount": 0.00, "status": "string" } Sua resposta anterior: { "invoice_id": null, "amount": "150.00", "status": "PAID" } Erros de validação: - invoice_id é null mas é um campo de string obrigatório — extraia-o da entrada - amount é uma string ("150.00") mas deve ser um float (150.00) - status deve ser em minúsculas: use 'paid', não 'PAID' Retorne apenas o objeto JSON corrigido.
Padrões de prompt para arrays, enums e campos anuláveis
Arrays, enums e campos anuláveis são as três fontes mais comuns de falhas em saída estruturada que o esquema no prompt sozinho não previne. Cada um requer um padrão de instrução específico no prompt.
| Tipo de dado | Falha comum | Padrão de prompt que a previne |
|---|---|---|
| Array (0 itens) | O modelo retorna null em vez de [] | "Retorne um array vazio [] se não houver itens presentes. Nunca retorne null para campos de array." |
| Array (1+ itens) | O modelo retorna um objeto único em vez de array quando apenas um item é encontrado | "Sempre retorne um array, mesmo quando há apenas um item. Itens únicos devem ser encapsulados: {...}" |
| Enum (2–5 valores) | O modelo abrevia ou inventa valores similares | "status: exatamente um de: 'active', 'inactive', 'pending' — sem abreviações ou variantes" |
| Enum (6+ valores) | O modelo inventa valores que não estão na lista | Liste todos os valores em uma lista numerada, depois: "Use apenas os valores da lista acima. Não abrevia nem combine valores." |
| Campo anulável | O modelo retorna "" em vez de null, ou omite o campo por completo | "Retorne null se o valor for desconhecido. Retorne string vazia '' apenas se souber que o campo está em branco. Sempre inclua o campo — não o omita." |
| Integer vs float | O modelo retorna float quando se espera integer, ou string para ambos | "score (integer — sem casas decimais, ex.: 4 não 4.0)" ou "price (float — exatamente 2 casas decimais, ex.: 12.99 não 13)" |
| Objeto aninhado | O modelo achata o objeto aninhado para chaves planas (ex.: "address.city" em vez de {"address": {"city": ...}}) | Mostre a estrutura aninhada completa no template do esquema com recuo correto. A descrição em linguagem natural do aninhamento frequentemente é achatada para chaves planas. |
Medir a confiabilidade da saída estruturada do seu prompt
Mire em 95%+ de taxa de aprovação em um conjunto de teste de 20 casos antes de fazer deploy de qualquer prompt de saída estruturada em produção. Meça a confiabilidade por campo, não apenas no geral.
- 1Defina critérios de aprovação/reprovação para cada campo do esquema. Para cada campo: o tipo está correto, o campo obrigatório está presente, o valor de enum está na lista permitida, o formato de data corresponde ao padrão exigido.
- 2Construa um conjunto de teste de 20 casos. Dez entradas de caminho feliz (dados típicos e bem formados), cinco casos extremos (campos opcionais ausentes, texto longo, valores incomuns), cinco entradas adversariais (instruções embutidas em valores de campos, datas extremas, tipos ambíguos).
- 3Execute a temperatura 0 e registre aprovação/reprovação por campo. Execute os 20 casos a temperatura 0 para resultados deterministas e repetíveis. Registre se cada campo aprova ou reprova em cada caso de teste.
- 4Corrija o campo com menor taxa de aprovação e teste novamente. Adicione ou reforce uma instrução de campo: tipo, formato, tratamento de null ou valores de enum. Execute novamente os 20 casos. Uma adição de instrução direcionada normalmente eleva a taxa de aprovação geral em 5–15 pontos percentuais.
- 5Valide o prompt em um segundo modelo. Execute o conjunto completo de 20 casos contra um segundo modelo usando o mesmo prompt. Um prompt a 95%+ no GPT-5.5 mas a 70% no Claude 4.6 Sonnet é dependente do modelo.
5 erros comuns em prompts de saída estruturada
Os cinco erros mais comuns em prompts de saída estruturada produzem todos o mesmo sintoma — falhas intermitentes ou sistemáticas — mas exigem correções diferentes.
❌ Descrever o esquema em linguagem natural em vez de incorporá-lo
Why it hurts: Descrições em linguagem natural são ambíguas — "uma lista de itens" pode significar um array, uma string separada por vírgulas ou uma lista numerada
Fix: Incorpore o esquema esperado como template JSON diretamente no prompt.
❌ Não especificar como tratar valores ausentes ou desconhecidos
Why it hurts: Os modelos inventam valores plausíveis para campos desconhecidos em vez de retornar null — datas viram "desconhecido", valores viram 0, IDs ausentes viram "N/A"
Fix: Adicione tratamento explícito de null para cada campo anulável: "Retorne null se o valor não puder ser determinado. Não adivinhe nem invente valores."
❌ Testar apenas contra o modelo no qual o prompt foi desenvolvido
Why it hurts: A confiabilidade da saída estruturada varia significativamente entre modelos — um prompt a 95% no GPT-5.5 pode falhar a 70% no Claude 4.6 Sonnet
Fix: Execute cada prompt de saída estruturada contra pelo menos 2 modelos antes de tratá-lo como agnóstico ao modelo.
❌ Tentar novamente a saída com falha usando exatamente o mesmo prompt
Why it hurts: Um prompt com falha tentado novamente a temperatura 0 produz a mesma falha toda vez
Fix: Use um prompt de correção com o erro de validação específico e a saída malformada, ou diagnostique o padrão de falha e adicione uma instrução de campo direcionada ao prompt base.
❌ Tratar o modo JSON como uma solução completa de saída estruturada
Why it hurts: O modo JSON evita saída não analisável, mas não falhas de conformidade com o esquema — um modelo usando o modo JSON pode retornar JSON válido com campos ausentes, tipos incorretos e valores de enum inválidos
Fix: Sempre inclua o esquema no prompt e instruções de campo mesmo ao usar o modo JSON imposto por API.
Perguntas frequentes
As perguntas mais comuns sobre prompting de saída estruturada cobrem o limite entre o modo JSON e o design do prompt, quantos exemplos incluir e como melhorar sistematicamente um prompt com falhas.
O modo JSON torna o esquema no prompt desnecessário?
Não. O modo JSON impõe a sintaxe JSON analisável, não a conformidade com o esquema. Um modelo usando o modo JSON ainda pode retornar JSON válido com campos obrigatórios ausentes, tipos de dados incorretos ou valores de enum inválidos. O esquema no prompt e as instruções de campo tratam das falhas de conformidade com o esquema; o modo JSON apenas evita saída não analisável. As duas abordagens são complementares, não alternativas.
Quantos exemplos de saída devo incluir no prompt?
Um exemplo geralmente é suficiente e adiciona o maior ganho de confiabilidade. Um segundo exemplo adiciona valor apenas quando seus dados têm uma estrutura significativamente diferente dependendo das condições de entrada. Além de dois exemplos, o custo em comprimento do prompt supera o benefício de confiabilidade para a maioria das tarefas de saída estruturada.
Devo usar JSON ou YAML para saída estruturada sem enforcement de API?
Use YAML quando gerar sem enforcement de API e a saída não precisar ser analisada por um sistema que espera JSON. Os modelos produzem menos erros de sintaxe em YAML porque ele não requer chaves de fechamento, sequências de escape ou rastreamento de vírgulas finais. Use JSON quando a saída alimenta diretamente uma API, banco de dados ou sistema posterior que requer JSON.
Qual é a forma mais rápida de melhorar um prompt com taxa de aprovação de 70%?
Execute o conjunto de teste por campo, não apenas no geral. Encontre o campo com a menor taxa de aprovação individual, adicione uma instrução explícita cobrindo tipo, formato e tratamento de null, depois execute novamente. Uma única instrução de campo direcionada normalmente eleva a taxa de aprovação geral em 5–15 pontos percentuais.
Como obter saída estruturada confiável de um modelo sem modo JSON nativo?
Incorpore o esquema JSON completo como template no prompt, inclua um exemplo de saída válida, adicione instruções por campo e execute a temperatura 0. Analise e valide cada saída; envie um prompt de correção para qualquer falha de validação. Prompts bem projetados atingem 85–92% de confiabilidade na maioria dos modelos a temperatura 0 sem modo JSON nativo.
Qual é o tamanho correto do conjunto de teste para um prompt de saída estruturada?
Mínimo de 20 casos: 10 entradas de caminho feliz (dados típicos e bem formados), 5 casos extremos (valores incomuns, campos opcionais ausentes, entradas longas), e 5 entradas adversariais.
Quando devo usar um prompt de correção versus corrigir o prompt base?
Use um prompt de correção quando as falhas são raras — menos de 10% das saídas. Corrija o prompt base quando as falhas são sistemáticas: o mesmo campo ausente ou o mesmo erro de tipo aparecendo em múltiplos casos de teste.
A ordem dos campos no esquema afeta a confiabilidade da saída estruturada?
Sim. Coloque os campos obrigatórios primeiro e os campos opcionais ou anuláveis por último. Os modelos ponderam mais os elementos anteriores do esquema ao decidir o que incluir. Esse efeito de ordenamento é consistente no GPT-5.5 e no Claude 4.6 Sonnet.
Leitura relacionada
- Saída estruturada e modo JSON: quando e como usar — Configuração do modo JSON a nível de API para GPT-5.5, Claude e Gemini com tabela de conformidade do modelo
- Como controlar a saída: formato, temperatura e decodificação restrita — mecânicas de decodificação restrita, temperatura e top-p para tarefas estruturadas
- Como avaliar a qualidade do prompt: métricas, testes e checklist — construção de conjuntos de teste de 20 casos, pontuação binária de aprovação/reprovação
- Como testar prompts em diferentes modelos — executar o mesmo prompt no GPT-5.5, Claude 4.6 Sonnet e Gemini 2.5 Pro para encontrar falhas específicas do modelo
- Zero-Shot vs Few-Shot Prompting — quando adicionar exemplos a um prompt e quantos incluir para diferentes tipos de tarefa
Fontes
- Documentação de Structured Outputs da OpenAI — especificação técnica para response_format e modo JSON na API da OpenAI
- Documentação de uso de ferramentas da Anthropic — como o parâmetro tool_use do Claude impõe a saída estruturada a nível de API
- Documentação de GenerationConfig do Google Gemini — configuração responseMimeType do Gemini para saída JSON nativa
- Benchmark BAML: compromissos de precisão em saída estruturada — evidência sobre diferenças de confiabilidade entre geração restrita e não restrita entre modelos
- Framework de Gestão de Riscos de IA do NIST — princípios de governança para validação de saída de IA em sistemas de produção