Blog do SchemaSafe
Validação de Esquema JSON sem um LLM
A validação de esquema pertence a ferramentas determinísticas: a mesma entrada produz o mesmo resultado de aprovação ou falha, sempre. Um LLM pode explicar por que um documento falhou ou criar um esquema a partir de um exemplo, mas a parte de aprovação ou falha deve vir de um validador real. Quando a fronteira entre explicação e decisão permanece clara, o contrato permanece algo que você pode testar e confiar.
O determinismo é o produto
Quando desenho um validador, foco-me na navegação pela árvore de instâncias. Cada passo produz um objeto de erro que transporta um caminho JSON Pointer, a palavra-chave que falha e uma mensagem curta. Como a navegação segue o mesmo algoritmo para os mesmos dados, a lista de erros é idêntica em cada execução. Essa repetibilidade permite que as equipas tratem a validação como um portão que nunca altera o seu veredicto sem uma alteração real no esquema ou na entrada.
Os caminhos JSON Pointer mapeiam diretamente para campos de formulário ou chaves de resposta de API. Um front-end pode tomar o ponteiro /items/2/name e realçar o campo de nome do terceiro item sem qualquer camada de tradução extra. Este mapeamento é determinístico, por isso o mesmo ponteiro sempre aponta para a mesma localização no mesmo formato de documento.
Na CI, executo o validador contra a suite de testes e contra qualquer fixture gerada. Se o validador devolver uma matriz de erros vazia, a compilação prossegue; qualquer matriz não vazia falha a compilação e a carga de erro é publicada como um artifact. Como a saída é legível por máquina, as etapas posteriores podem contar erros, agrupá-los por ponteiro ou publicar um comentário no pedido de pull request que mostra os caminhos exatos que falharam.
Onde um LLM ganha o seu lugar
Utilizo um modelo de linguagem apenas para tarefas que não exigem um veredicto verdadeiro/falso. O modelo nunca decide passar ou falhar; ele apenas produz sugestões que um humano ou uma ferramenta podem rever.
Dado um punhado de documentos JSON de exemplo, peço ao modelo que emita um esquema Draft 2020-12 que capture os tipos observados, os campos obrigatórios e os padrões básicos. A saída é um ponto de partida; eu executo-o no validador para ver se ele aceita os exemplos e, em seguida, ajusto ou relaxo as restrições manualmente.
Quando o validador retorna uma matriz de erros, eu forneço cada objeto de erro ao modelo com um pedido para reescrever a mensagem em linguagem simples. O modelo pode transformar “falha na palavra-chave ‘obrigatório’ no ponteiro /user/profile/age” em “O perfil do usuário está faltando um campo de idade, que o seu serviço espera que seja um inteiro.” Isso ajuda os consumidores de API que não estão familiarizados com palavras-chave do JSON Schema.
Ao mostrar ao modelo uma lista de erros de validação frequentes, posso pedir que ele proponha restrições adicionais, como um comprimento mínimo de string ou um padrão para um identificador. Eu revejo cada sugestão, adiciono as que fazem sentido e executo o validador novamente para confirmar que o novo esquema ainda passa nos exemplos bons conhecidos.
Para garantir a segurança, mantenho o modelo atrás de uma API interna e registro cada prompt e resposta. O registro permite que eu audite se o modelo já tentou influenciar a fronteira de decisão, o que ele não pode fazer porque nunca passo sua saída para o validador como uma regra.
Executar validação em CI e na borda
O mesmo esquema deve proteger o repositório de código e o serviço ao vivo. Eu executo o validador em dois lugares:
Executar a validação apenas em um gateway deixa o serviço interno exposto a deriva; se o esquema do gateway for atualizado, mas um serviço downstream esquecer de puxar a alteração, dados ruins podem passar. Ao incorporar o validador no serviço, eu garanto que o contrato é aplicado onde quer que o código viva.
Quando a validação falha, eu retorno HTTP 400 com um corpo JSON que contém uma matriz de objetos de erro. Cada objeto de erro inclui:
Os clientes podem analisar esta matriz e mostrar erros de formulário inline, o que acelera o trabalho de integração em comparação com uma string genérica de "validação falhou".
Como o validador é sem estado e determinístico, eu posso usar o mesmo binário ou biblioteca em ambos os lugares sem me preocupar com estado oculto que possa causar divergência.
Geração de rascunho versus governança
O SchemaSafe separa claramente as preocupações:
Esta divisão mantém o contrato auditável. Posso apontar para um arquivo de esquema específico no repositório, notar a versão do validador e mostrar que a mesma entrada sempre produz o mesmo resultado. A contribuição do modelo vive em logs separados ou em comentários anexados ao pedido de pull; ele nunca se torna parte do registo de decisão imutável.
Quando preciso atualizar o esquema, sigo estes passos:
Ao longo deste fluxo, o validador é o guardião; o modelo nunca tem a palavra final.
O que isto não é
Esta abordagem não é uma promessa de que todos os documentos inválidos sejam detectados antes de chegarem a um utilizador. Se um desenvolvedor contornar deliberadamente o middleware ou se um bug no validador deixar passar um erro, dados incorrectos ainda podem aparecer. Não afirmo uma cobertura de 100 %; apenas afirmo que a verificação é determinística e repetível.
Não é um substituto para um design de API bem pensado. Um esquema pode descrever a forma e as restrições básicas, mas não pode expressar regras de negócio que dependam de estado externo ou lógica complexa entre campos. Essas regras ainda necessitam de testes unitários ou guardas de tempo de execução.
Não é uma garantia de que o LLM sempre produzirá explicações úteis. O modelo pode ocasionalmente perder nuances ou produzir uma reescrita enganosa. Trato a sua saída como uma sugestão que um humano pode aceitar, editar ou descartar.
Por fim, não é uma bala de prata para a segurança. Embora a validação de entrada reduza muitos riscos de injeção, ainda sigo as orientações da OWASP sobre injeção de prompt ( https://genai.owasp.org/llmrisk/llm01-prompt-injection ) e sobre higiene de credenciais em CI/CD ( https://owasp.org/www-project-top-10-ci-cd-security-risks/CICD-SEC-06-Insufficient-Credential-Hygiene ) para manter o pipeline circundante seguro.
Referências
https://genai.owasp.org/llmrisk/llm01-prompt-injection
https://owasp.org/www-project-top-10-ci-cd-security-risks/CICD-SEC-06-Insufficient-Credential-Hygiene
https://ajv.js.org/json-schema.html
https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html
Perguntas Frequentes
A validação deve ser reproduzível: mesmo input, mesmo resultado. O julgamento de um modelo pode variar entre execuções, o que é inaceitável para um contrato que controla uma implementação. O validador decide; o modelo explica.
Criar um esquema a partir de um exemplo, reescrever um erro de validação para um humano ou sugerir por que um campo foi omitido. Essas são assistências adicionais a um validador real, não um substituto para um.
Não. Valide as solicitações de entrada no serviço que controla para que as mensagens de erro incluam o contexto do domínio. Execute o mesmo esquema no CI contra fixtures e trate as alterações no esquema como alterações potencialmente disruptivas.
O rascunho 2020-12 é a versão estável suportada por validadores modernos, como o Ajv v8, e alinhada com o OpenAPI 3.1. Prenda a URL do esquema em cada arquivo para que o comportamento não se desvie.
Experimente o produto: SchemaSafe
2026-09-16 · apenas fontes primárias · sem métricas de tráfego fabricadas
Artigos relacionados
Erros comuns de autorização de esquema JSON
Explore a matriz completa de tópicos de micro-SaaS de IA →
Por que não deixar um LLM decidir se o JSON é válido?
A validação deve ser reprodutível: mesmo input, mesmo resultado. O julgamento de um modelo pode variar entre execuções, o que é inaceitável para um contrato que controla uma implantação. O validador decide; o modelo explica.
Onde um LLM é genuinamente útil para esquemas?
Criar um esquema a partir de um exemplo, reescrever um erro de validação para um humano ou sugerir por que um campo foi omitido. Essas são assistências em cima de um validador real, não um substituto para um.
A validação deve ser executada apenas no gateway?
Não. Valide as solicitações de entrada no serviço que você controla para que as mensagens de erro incluam o contexto do domínio. Execute o mesmo esquema no CI contra fixtures e trate as alterações de esquema como possíveis alterações quebradoras.
Qual é o rascunho atual do JSON Schema para fixar?
O rascunho 2020-12 é a versão estável suportada por validadores modernos, como o Ajv v8, e alinhada com o OpenAPI 3.1. Fixe a URL do $schema em cada arquivo para que o comportamento não se desvie.
Apoio à decisão apenas. Não é um substituto para uma revisão formal de esquema ou auditorias certificadas.