Blog do SchemaSafe
Erros comuns de autorização de esquema JSON
O esquema JSON, atualmente Rascunho 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 aparecem na revisão de código são uma matriz requerida ausente, uma propriedade adicional aberta, uniões de tipo mal utilizadas e um $ref que aponta para lugar nenhum.
Esquecendo o array necessário
Quando você adiciona uma propriedade sob propriedades, está apenas descrevendo sua forma, não exigindo sua presença. Se o array necessário omitir essa chave, uma instância sem o campo é validada com sucesso. Isso é uma aprovação silenciosa porque o validador trata a propriedade como opcional. Eu já vi equipes lançarem 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.
Deixando 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", então se torna um campo aceito silenciosamente, poluindo o modelo de dados e tornando as migrações posteriores mais difíceis. Eu já vi equipes gastarem semanas limpando chaves indesejadas 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 esse 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 inadequada
A palavra-chave type espera uma string ou uma matriz 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 inteiramente para um campo opcional, o que faz com que o validador pule a verificação de tipo para essa chave.
Exemplo de um campo de data nulo:
{ "type": "object", "properties": { "issuedAt": { "type": ["string","null"], "format": "date-time" } }, "required": ["issuedAt"] } Aqui, null é permitido, então {"issuedAt":null} é aprovado, enquanto {"issuedAt":"not-a-date"} falha.
Armadilhas de $ref e derivação de versão
Um $ref que resolve para uma localização inexistente causa a falha do esquema inteiro no momento do carregamento, o que é barulhento 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 foi movida 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ção.
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 incorretamente "$ref": "#/definitions/address" a referência resolveria para indefinido e o validador lançaria um erro, alertando-o sobre a incompatibilidade.
Validar com amostras antes de publicar
A verificação de confiança mais barata é executar um punhado de instâncias JSON representativas pelo validador antes de tratar o esquema como um contrato. Um bom conjunto de testes contém pelo menos um exemplo válido que corresponde ao uso pretendido e um exemplo inválido que deliberadamente viola cada regra que você se importa. Se o esquema aceitar a amostra boa e rejeitar a ruim, você terá evidências de que ele não é excessivamente permissivo. Eu já vi equipes pularem esta etapa e mais tarde descobrirem que um requisito ausente permitia que pedidos sem IDs de produto passassem, 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" }; // ID ausente 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 no CI garante que um erro permissivo nunca alcance a produção.
O que isso não é
Este guia não promete que seguir esses pontos tornará seu esquema imune a todos os possíveis erros. O JSON Schema é uma linguagem flexível, e novas armadilhas podem aparecer à medida que você o estende com palavras-chave personalizadas ou o combina com outras ferramentas como OpenAPI. Não estou afirmando que os quatro erros listados sejam os únicos que importam; eles são simplesmente os que aparecem com mais frequência nas revisões de código que eu vi. Os conselhos aqui são baseados na minha experiência mantendo o SchemaSafe e nas especificações publicamente disponíveis; eles não substituem a leitura da especificação oficial ou a execução de seus próprios testes de validação.
Referências
https://ajv.js.org/json-schema.html
https://developer.mozilla.org/pt-BR/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. Você deve listá-la no array de propriedades obrigatórias. O array é um irmão de propriedades, não aninhado dentro dele.
Ele é true por padrão, então chaves desconhecidas são aprovadas. 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-o do obrigatório e inclua "null" no array de tipo, 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
16-09-2026 · somente fontes primárias · sem métricas de tráfego fabricadas
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 meu esquema aceita campos faltantes?
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 padrão?
Ele é padrão como true, então 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 prenda $schema para que o validador aplique o rascunho que você pretendia.
Apenas para suporte à decisão. Não é um substituto para uma revisão formal de esquema ou auditorias certificadas.