JSON Schema Validator

O que é JSON Schema e por que é importante?

JSON (JavaScript Object Notation) é a língua franca das APIs web, ficheiros de configuração e intercâmbio de dados. Mas o JSON puro não tem um sistema de tipos incorporado — um campo pode ser uma string num dia e um número no seguinte, e a única forma de descobrir a incompatibilidade é um erro em tempo de execução ou um bug de dados subtil. O JSON Schema preenche essa lacuna: é um vocabulário declarativo para descrever a estrutura esperada e as restrições de um documento JSON, validado contra dados reais em tempo de execução.

As equipas utilizam JSON Schema para validar cargas úteis de pedidos de API antes de as processar, para fazer cumprir a forma dos ficheiros de configuração carregados no arranque, para gerar automaticamente documentação e formulários de UI a partir de uma única fonte de verdade, e para manter a consistência de contratos entre microsserviços. OpenAPI — o padrão para documentação de APIs REST — é construído diretamente sobre JSON Schema, tornando-o o padrão de validação de dados mais amplamente implementado na web.

Versões do rascunho de JSON Schema: Draft-07, Draft 2019-09 e Draft 2020-12

O JSON Schema passou por vários rascunhos de especificação. O Draft-07, lançado em 2018, continua a ser o mais amplamente suportado em todas as principais bibliotecas de validadores e é o dialeto utilizado pelo OpenAPI 3.0. Introduziu as poderosas palavras-chave de validação condicional if/then/else, as anotações de propriedade readOnly/writeOnly e as palavras-chave de codificação de conteúdo. Se está a escrever esquemas hoje e não necessita das funcionalidades mais recentes, o Draft-07 é a escolha mais segura para máxima compatibilidade com o ecossistema.

O Draft 2020-12 é a especificação estável atual e introduz várias alterações significativas: a palavra-chave items é substituída por prefixItems para validação de tuplos, as referências dinâmicas utilizam $dynamicRef em vez de $recursiveRef, e as novas palavras-chave unevaluatedProperties e unevaluatedItems fornecem controlo mais preciso sobre conteúdo adicional.

Palavras-chave principais do JSON Schema explicadas

A palavra-chave type impõe um tipo de dados: string, number, integer, boolean, array, object ou null. required lista as propriedades que devem estar presentes num objeto. properties mapeia cada nome de propriedade para o seu próprio subesquema. pattern aplica uma expressão regular a um valor de string. minimum, maximum, minLength e maxLength restringem intervalos numéricos e de string. enum restringe um valor a um conjunto fixo de valores permitidos; const restringe-o a um único valor.

As palavras-chave de composição permitem-lhe construir regras complexas a partir de blocos de construção simples: allOf funciona como AND lógico, anyOf como OR e oneOf como XOR. A palavra-chave not inverte um esquema. As palavras-chave if/then/else permitem a validação condicional. Juntas, permitem-lhe expressar quase qualquer regra de validação sem escrever código imperativo personalizado.

JSON Schema em produção: contratos de API e pipelines de CI

Em sistemas de produção, a validação de JSON Schema corre do lado do servidor ou em pipelines de CI usando bibliotecas como Ajv (JavaScript/Node.js), jsonschema (Python) ou Newtonsoft.Json (C#). Os esquemas são submetidos ao controlo de versões juntamente com o código da aplicação para que as alterações de contrato sejam revistas e rastreadas como qualquer outra alteração. As alterações disruptivas — remover um campo obrigatório, restringir um tipo — são detetadas na revisão de código antes de chegarem à produção.

Esta ferramenta baseada no navegador é ideal para conceber e depurar esquemas iterativamente antes de os submeter. Cole os seus dados, escreva o seu esquema, clique em Validar, leia as mensagens de erro detalhadas e refine — sem servidor, sem npm install, sem viagens de ida e volta. O validador também formata o seu JSON em cada execução de validação, tornando-o um prático combinado de formatador JSON e testador de esquemas.

Exemplo prático: Validando uma resposta de API

Suponha que a sua API devolve um objeto de utilizador. Um JSON Schema que o valida pode requerer um id inteiro, um nome de string não vazio, um email de string correspondente a um padrão de email e um papel de string opcional de um enum de 'admin', 'editor' e 'viewer'. Definir additionalProperties como false garante que a sua API nunca devolve silenciosamente campos não documentados dos quais os consumidores posteriores possam inadvertidamente depender.

A funcionalidade if/then/else permite regras condicionais — por exemplo, se o papel for 'admin' então é necessário um array de permissões, caso contrário está proibido. Estas regras composicionais permitem que um único esquema cubra múltiplas formas válidas de um objeto sem duplicar definições de propriedades.

Como o UtiloKit se compara a outros validadores de JSON Schema

A maioria das ferramentas de validação de JSON Schema online enquadra-se em duas categorias: construtores visuais de esquemas e validadores de API do lado do servidor. O jsonschema.net obriga-o a passar por uma UI de apontar e clicar para construir esquemas — é útil para principiantes que aprendem a estrutura de esquemas, mas lento para programadores que já sabem que palavras-chave precisam.

O jsonschemavalidator.net, construído sobre a biblioteca Newtonsoft.Json da Microsoft, reporta erros usando caminhos de propriedade .NET e códigos de erro que parecem desconhecidos para programadores JavaScript. Ferramentas como Stoplight e SwaggerHub validam esquemas como parte de um documento OpenAPI completo e requerem configuração de projeto e conta.

O validador do UtiloKit corre no mesmo motor Ajv que alimenta a maioria das aplicações Node.js, Express e Fastify. As mensagens de erro, os caminhos de ponteiro JSON e o comportamento das palavras-chave correspondem exatamente ao seu ambiente de produção — e corre gratuitamente no seu navegador sem conta, sem carregamento, sem limite de tamanho de ficheiro e sem limite de utilização diária.