Blog do SchemaSafe
Erros comuns de autorização de esquemas JSON
O esquema JSON, atualmente Draft 2020-12, é a forma padrão de descrever e validar a forma do JSON. A maioria dos esquemas quebrados não são erros de sintaxe; são erros permissivos que permitem dados inválidos. Os quatro que mais surgem na revisão de código são uma matriz requerida em falta, uma propriedade adicional aberta, uniões de tipo mal utilizadas e um $ref que aponta para lugar nenhum.
Esquecendo o array obrigatório
Quando adiciona uma propriedade sob propriedades, está apenas descrevendo a sua forma, não exigindo a sua presença. Se o array obrigatório omitir essa chave, uma instância sem o campo valida com sucesso. É uma aprovação silenciosa porque o validador trata a propriedade como opcional. Já vi equipes lançar APIs onde um identificador crítico estava faltando no required, levando a erros de ponteiro nulo downstream que só apareciam em produção.
Por exemplo, um esquema de usuário que espera um id deve conter:
{ "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id"] } Sem a linha required, um objeto com apenas {"name":"Ada"} seria aprovado, mesmo que a API posteriormente trate o id como obrigatório.
Deixar additionalProperties aberto
O valor padrão de additionalProperties é true. Isso permite que qualquer chave não definida em properties passe pela validação. Um erro de digitação, como "user_name" em vez de "username", torna-se então um campo aceite silenciosamente, poluindo o modelo de dados e tornando as migrações posteriores mais difíceis. Eu já vi equipes gastarem semanas limpando chaves errantes que entraram no banco de dados porque o esquema nunca as rejeitou.
Aqui está uma versão estrita de um esquema de produto:
{ "type": "object", "properties": { "sku": { "type": "string" }, "price": { "type": "number", "minimum": 0 } }, "required": ["sku","price"], "additionalProperties": false } Com este esquema, uma instância contendo {"sku":"ABC","price":10,"extra":1} falha na validação, capturando o erro de digitação precocemente.
Usando uniões de tipo de forma incorrecta
A palavra-chave type espera uma string ou um array de strings. Escrever "type": "string, number" é um esquema JSON inválido; o analisador trata o valor inteiro como um tipo desconhecido, que muitos validadores ignoram silenciosamente, permitindo que qualquer valor seja aprovado. Outro erro comum é omitir o tipo completamente para um campo opcional, o que faz com que o validador salte a verificação de tipo para essa chave.
Exemplo de um campo de data anulável:
{ "type": "object", "properties": { "issuedAt": { "type": ["string","null"], "format": "date-time" } }, "required": ["issuedAt"] } Aqui, o null é permitido, então {"issuedAt":null} é aprovado, enquanto {"issuedAt":"not-a-date"} falha.
Armadilhas de $ref e deriva de versão
Um $ref que resolve para uma localização inexistente causa a falha do esquema inteiro no momento do carregamento, o que é ruidoso e fácil de detectar. O problema mais silencioso é uma referência que resolve, mas aponta para a definição errada porque a versão do rascunho mudou ou a estrutura de pastas mudou. No Rascunho 2020-12, a palavra-chave para blocos reutilizáveis mudou de definições para $defs. Se você manter a chave antiga, o esquema ainda valida (a palavra-chave mais antiga é ignorada), mas você perde a capacidade de reutilizar definições, levando a código duplicado e deriva.
Exemplo de referência correta:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" } }, "required": ["street","city"] } }, "type": "object", "properties": { "billing": { "$ref": "#/$defs/address" }, "shipping": { "$ref": "#/$defs/address" } }, "required": ["billing","shipping"] } Se você escrevesse por engano "$ref": "#/definitions/address" a referência resolveria para indefinido e o validador lançaria um erro, alertando-o para a incompatibilidade.
Validar com amostras antes de publicar
A verificação de confiança mais barata é executar um punhado de instâncias JSON representativas através do validador antes de tratar o esquema como um contrato. Um conjunto de testes bom contém pelo menos um exemplo válido que corresponde ao uso pretendido e um exemplo inválido que deliberadamente viola cada regra que lhe importa. Se o esquema aceitar a amostra boa e rejeitar a ruim, você tem evidências de que não é excessivamente permissivo. Eu vi equipes saltar este passo e mais tarde descobrir que um requisito ausente permitia pedidos sem IDs de produto escorregarem, causando erros de cumprimento.
const Ajv = require('ajv'); const ajv = new Ajv({allErrors: true}); const schema = require('./user-schema.json'); const good = { "id": "123", "name": "Ada" }; const bad = { "name": "Ada" }; // missing id const validate = ajv.compile(schema); console.log('Amostra boa:', validate(good) ? 'pass' : 'fail'); if (!validate(good)) console.error(validate.errors); console.log('Amostra ruim:', validate(bad) ? 'pass' : 'fail'); if (validate(bad)) console.error('Amostra ruim aceita inesperadamente'); Executar isso em CI garante que um erro permissivo nunca alcance a produção.
O que isto não é
Este guia não promete que seguir estes pontos tornará o seu esquema imune a todos os possíveis erros. O JSON Schema é uma linguagem flexível, e novas armadilhas podem aparecer à medida que o estende com palavras-chave personalizadas ou o combina com outras ferramentas como o OpenAPI. Não estou a afirmar que os quatro erros listados sejam os únicos que importam; são simplesmente os que aparecem com mais frequência nas análises de código que vi. Os conselhos aqui apresentados baseiam-se na minha experiência de manutenção do SchemaSafe e nas especificações publicamente disponíveis; não substituem a leitura da especificação oficial ou a execução dos seus próprios testes de validação.
Referências
https://ajv.js.org/json-schema.html
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
https://json-schema.org
https://json-schema.org/draft/2020-12/json-schema-core.html
Perguntas Frequentes
Declarar uma propriedade em propriedades não a torna obrigatória. É necessário listá-la na matriz de requisitos. A matriz é uma irmã de propriedades, não aninhada dentro dela.
Ele é true por padrão, então as chaves desconhecidas passam. Defina additionalProperties: false onde a rigidez é importante, ou restrinja-o com um esquema para campos de extensão. Esquemas abertos permitem que erros de digitação passem silenciosamente.
Omita-a da lista de requisitos e inclua "null" na matriz de tipos, por exemplo ["string", "null"]. Escrever uma string de tipo separada por vírgulas é inválida e pode anular a restrição.
Em $defs. A chave de definições mais antiga ainda funciona, mas marca um rascunho antigo. Sempre fixe $schema para que o validador aplique o rascunho que você pretendia.
Experimente o produto: SchemaSafe
2026-09-16 · apenas fontes primárias · nenhum tráfego métrico fabricado
Artigos relacionados
Validação de esquema JSON sem um LLM (2026)
Explore a matriz completa de tópicos de micro-SaaS de IA →
Por que o meu esquema aceita campos em falta?
Declarar uma propriedade em properties não a torna obrigatória. Você deve listá-la no array required. O array é um irmão de properties, não aninhado dentro dele.
O que additionalProperties faz por predefinição?
Ele é predefinido para true, por isso as chaves desconhecidas passam. Defina additionalProperties: false onde a rigidez é importante, ou restrinja-o com um esquema para campos de extensão. Esquemas abertos permitem que erros de digitação passem silenciosamente.
Como marco um campo como opcional no JSON Schema?
Omita-o de required e inclua \
Onde as definições reutilizáveis vão no Draft 2020-12?
Embaixo de $defs. A chave definitions mais antiga ainda funciona, mas marca um rascunho antigo. Sempre fixe $schema para que o validador aplique o rascunho que você pretendeu.
Apenas para suporte à decisão. Não substitui a revisão formal de esquemas ou auditorias certificadas.