Um modelo pode devolver um texto convincente e ainda produzir dados que o sistema não consegue usar. Um valor monetário pode vir em formato inesperado, um identificador pode ser inventado e uma informação ausente pode aparecer como certeza. Para integrar IA a processos, a aplicação precisa de um contrato explícito.
JSON Schema ajuda a descrever a estrutura esperada. Ele não comprova que o conteúdo é verdadeiro nem substitui regras de negócio. O projeto profissional combina estrutura, evidência e autorização. Este guia mostra como separar essas responsabilidades e evitar que uma resposta formalmente válida cause uma operação errada.
Estrutura é a primeira camada de validação
A referência oficial sobre objetos em JSON Schema explica propriedades, obrigatoriedade e tratamento de campos adicionais. Declarar uma propriedade não a torna obrigatória automaticamente. Esse detalhe importa quando o sistema espera uma informação que o modelo pode omitir.
Defina tipos, campos obrigatórios e política para propriedades extras. Considere a versão do schema e o validador utilizado. Recursos aceitos por uma biblioteca podem não ser suportados da mesma forma por uma integração de geração estruturada.
O contrato deve representar a necessidade do sistema, sem tentar acomodar qualquer resposta. Aceitar um campo livre para tudo reduz a utilidade da validação e transfere ambiguidade para etapas posteriores.
| Camada | Pergunta respondida | Exemplo de falha |
|---|---|---|
| Sintaxe | É um documento legível? | JSON incompleto |
| Estrutura | Segue o contrato? | Campo obrigatório ausente |
| Semântica | Os valores fazem sentido? | Data final anterior à inicial |
| Evidência | A informação foi encontrada? | Número de contrato inventado |
| Autorização | A operação é permitida? | Alteração por usuário sem acesso |
Modele ausência e dúvida sem forçar preenchimento
Um campo obrigatório mal desenhado pode incentivar o preenchimento de uma lacuna com uma suposição. Diferencie informação disponível, não encontrada, ilegível e ainda não confirmada. A maneira concreta de representar esses estados depende do contrato e do mecanismo de geração utilizado.
Para uma extração documental, preserve o valor original e a interpretação normalizada quando isso ajuda a auditoria. Um texto de data ambígua deve ser encaminhado para conferência, em vez de convertido silenciosamente. A aplicação decide quais estados impedem a continuidade.
Evite confundir pontuação de confiança produzida pelo próprio modelo com probabilidade calibrada. Uma nota alta não é evidência independente. Se o valor é decisivo, compare com fonte e regra apropriadas.
Regras semânticas pertencem ao domínio
O schema pode restringir formatos e valores, mas decisões de negócio dependem de contexto. Um desconto numericamente válido pode ultrapassar a alçada de quem solicita. Um código de produto bem formado pode não existir no catálogo atual.
Depois da validação estrutural, consulte os sistemas responsáveis. Verifique relacionamentos, situação e vigência. Se uma regra muda, registre a versão aplicada ao resultado. Isso permite entender por que um dado foi aceito ontem e rejeitado hoje.
A resposta de erro também precisa de contrato. Informe qual campo falhou e se o cliente pode corrigir a entrada, se a aplicação deve tentar novamente ou se é necessário atendimento humano. Repetir a mesma chamada sem nova informação costuma apenas reproduzir o problema.
Exemplo hipotético: extração de um pedido de compra
Uma indústria recebe pedidos em PDF. A IA identifica fornecedor, itens, quantidades e data solicitada. O JSON passa no schema, mas o fornecedor está inativo e um item não pertence à lista autorizada.
O processo não registra o pedido como aprovado. Ele guarda a extração e abre duas pendências. O usuário vê o trecho de origem e pode corrigir um código ou solicitar análise. Campos válidos permanecem preservados, sem obrigar a digitar tudo novamente.
Em outro arquivo, a data não está legível. O contrato permite representar essa ausência e o sistema solicita confirmação. Essa escolha evita transformar um requisito técnico de preenchimento em uma promessa de prazo ao fornecedor.
Versione contratos e consumidores
Adicionar um campo pode parecer inofensivo, mas um consumidor que rejeita propriedades desconhecidas pode falhar. Mudar um campo de opcional para obrigatório também altera o comportamento de registros antigos. Documente compatibilidade e migração.
Mantenha exemplos válidos e inválidos junto ao contrato. Inclua casos extremos, valores ausentes e caracteres inesperados. Os testes devem cobrir tanto o produtor quanto o consumidor da saída. Se existem vários modelos, execute a mesma bateria em cada um.
Separe mudanças de prompt, schema e regra operacional. Quando as três são alteradas juntas, fica difícil identificar o motivo de uma regressão. Uma atualização controlada permite comparar resultados e retornar ao comportamento anterior quando necessário.
Oficina: encontre um dado correto na forma e errado no negócio
Crie cinco pedidos fictícios que respeitam o formato, mas violam regras diferentes: fornecedor inativo, item inexistente, valor acima da alçada, data incoerente e unidade divergente. Acrescente dois documentos incompletos.
O exercício exige que a aplicação classifique a falha sem inventar uma correção. Defina quais casos podem continuar parcialmente e quais bloqueiam a operação inteira. O resultado é uma matriz de validação que orienta desenvolvimento, atendimento e aceite do projeto.
Faça o contrato ser compreensível para quem atende
A validação também aparece na experiência do usuário. Quando um campo falha, a interface deve explicar a pendência em linguagem de negócio. Exibir uma mensagem interna sobre o schema pode ser útil ao desenvolvedor, mas não ajuda necessariamente quem precisa concluir um pedido.
Defina quais dados podem ser corrigidos pelo usuário e quais exigem consulta a outra fonte. Uma pessoa pode esclarecer um nome, mas não deveria inventar um identificador de fornecedor para satisfazer a estrutura. A aplicação mantém as partes já verificadas e solicita apenas o que falta.
Ao homologar, entregue exemplos de respostas rejeitadas ao time de atendimento. Peça que ele explique o próximo passo. Se a orientação varia conforme quem lê o erro, o contrato operacional precisa ser refinado. Esse trabalho reduz solicitações repetidas e evita que uma barreira técnica seja resolvida por preenchimento arbitrário.
Registre também quais falhas foram detectadas antes de qualquer efeito externo. Esse indicador ajuda a avaliar a proteção do processo sem confundir bloqueios corretos com indisponibilidade técnica.
Checklist de implementação
- Definir versão e validador do schema.
- Declarar obrigatoriedade de forma explícita.
- Representar ausência e informação não confirmada.
- Validar regras de negócio fora do modelo.
- Consultar fontes responsáveis por identificadores.
- Versionar contratos e consumidores.
- Testar respostas válidas na forma e inválidas no domínio.
Baixe o checklist editável para sua equipe e registre responsáveis, verificações e decisões.
Perguntas frequentes
JSON válido significa informação correta?
Não. A sintaxe e a estrutura podem estar corretas enquanto os valores são falsos, incoerentes ou não autorizados.
Devo pedir ao modelo para corrigir qualquer erro?
Não automaticamente. Algumas falhas exigem dados novos ou decisão humana. A correção não pode inventar informações ausentes.
Um schema elimina a necessidade de testes?
Não. Ele é parte dos testes e da validação em execução. Regras semânticas, integração e autorização precisam de verificação própria.
Integre IA com contratos verificáveis
A Agência A2CR pode estruturar validação e integração de dados no seu processo. Converse sobre respostas estruturadas e regras de negócio.
Fontes consultadas
Revisão documental: 17/11/2026. Recursos, requisitos e condições podem mudar. Exemplos hipotéticos não representam resultados medidos de clientes.



