Blog SchemaSafe

Validação de esquema JSON sem LLM

A validação de esquema pertence a ferramentas determinísticas: a mesma entrada produz o mesmo resultado de aprovação ou reprovação, 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 reprovação 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 projeto um validador, me concentro na caminhada pela árvore de instâncias. Cada etapa produz um objeto de erro que carrega um caminho JSON Pointer, a palavra-chave que falhou e uma mensagem curta. Como a caminhada segue o mesmo algoritmo para os mesmos dados, a lista de erros é idêntica em cada execução. Essa repetibilidade permite que as equipes tratem a validação como um portão que nunca muda seu veredito sem uma mudança 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 pegar o ponteiro /items/2/name e destacar o campo de nome do terceiro item sem qualquer camada de tradução extra. Esse mapeamento é determinístico, então o mesmo ponteiro sempre aponta para a mesma localização no mesmo formato de documento.

No CI, executo o validador contra a suíte de testes e contra quaisquer fixtures gerados. Se o validador retornar 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 postar um comentário na solicitação de pull que mostra os caminhos exatos que falharam.

Onde um LLM ganha seu lugar

Eu uso um modelo de linguagem apenas para tarefas que não exigem um veredito verdadeiro/falso. O modelo nunca decide passar ou falhar; ele apenas produz sugestões que um humano ou uma ferramenta pode revisar.

Dado um punhado de documentos JSON de amostra, eu solicito ao modelo que emita um esquema Draft 2020-12 que capture os tipos observados, campos obrigatórios e 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 seu serviço espera ser um inteiro.” Isso ajuda os consumidores de API que não estão familiarizados com palavras-chave do esquema JSON.

Ao mostrar ao modelo uma lista de erros de validação frequentes, eu posso pedir que ele proponha restrições adicionais, como um comprimento mínimo de string ou um padrão para um identificador. Eu reviso cada sugestão, adiciono as que fazem sentido e executo o validador novamente para confirmar que o novo esquema ainda passa nas amostras boas conhecidas.

Para segurança, eu mantenho o modelo atrás de uma API interna e registro cada prompt e resposta. O registro me permite auditar se o modelo já tentou influenciar a fronteira de decisão, o que ele não pode fazer porque eu nunca passo sua saída para o validador como uma regra.

Execute 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 divergências; se o esquema do gateway for atualizado, mas um serviço downstream esquecer de baixar 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 resida.

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 essa matriz e exibir 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 as preocupações de forma clara:

Essa divisão mantém o contrato auditable. Posso apontar para um arquivo de esquema específico no repositório, observar 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 à solicitação de pull; ela nunca se torna parte do registro de decisão imutável.

Quando preciso atualizar o esquema, sigo os seguintes passos:

Ao longo desse fluxo, o validador é o guardião; o modelo nunca tem a palavra final.

O que isso não é

Essa abordagem não é uma promessa de que todos os documentos inválidos serão detectados antes de alcançar um usuário. Se um desenvolvedor deliberadamente contornar o middleware ou se um bug no validador deixar um erro passar, dados ruins ainda podem aparecer. Eu não afirmo cobertura de 100 %; eu 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ócios que dependam de estado externo ou lógica complexa de campo cruzado. Essas regras ainda precisam 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. Eu trato sua saída como uma sugestão que um ser humano pode aceitar, editar ou descartar.

Finalmente, não é uma bala de prata para a segurança. Embora a validação de entrada reduza muitos riscos de injeção, eu 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 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.

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.

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 no esquema como possíveis alterações quebradoras.

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.

Tente o produto: SchemaSafe

2026-09-16 · fontes primárias apenas · nenhum tráfego métrico fabricado