JSON Schema is a declarative language that allows you to annotate and validate JSON documents. It defines the structure, data types, and constraints of your JSON data.

Why should I use JSON Schema?

It ensures data integrity, provides automatic documentation for your API, and simplifies client-side and server-side validation logic.

Guia Completo de Validação de JSON Schema: Garantindo a Integridade dos Dados

No cenário moderno do desenvolvimento de software, os dados são o sangue vital de cada aplicação. Seja trocado entre microsserviços, enviado de um cliente para um servidor ou armazenado em um banco de dados NoSQL, a integridade e a estrutura desses dados são primordiais. O JSON (JavaScript Object Notation) tornou-se o padrão de facto para troca de dados devido à sua simplicidade e formato legível por humanos. No entanto, a flexibilidade do JSON também pode ser uma fraqueza: sem uma maneira de impor regras, sua aplicação pode receber dados inesperados, levando a falhas, vulnerabilidades de segurança ou estados inconsistentes.

É aqui que entra o JSON Schema. Ele fornece uma linguagem declarativa poderosa para anotar e validar documentos JSON, garantindo que eles sigam uma estrutura predefinida. Neste guia, exploraremos tudo, desde conceitos básicos até a composição avançada de esquemas.

O que é JSON Schema?

JSON Schema é um vocabulário que permite anotar e validar documentos JSON. Pense nele como uma "planta" para seus dados. Assim como um esquema de banco de dados define as colunas e tipos em uma tabela, um JSON Schema define as chaves, tipos e restrições de um objeto JSON.

É um padrão IETF (atualmente em vários rascunhos) que fornece uma maneira clara de:

Descrever seu formato de dados existente.
Fornecer documentação clara, legível por humanos e máquinas.
Validar dados para testes automatizados e validação do lado do cliente/servidor.

Ao usar o JSON Schema, você move a lógica de validação do seu código imperativo (instruções if) para um formato declarativo que pode ser compartilhado entre diferentes linguagens de programação e plataformas.

Conceitos Básicos e Tipos Primitivos

Cada JSON Schema é, por si só, um objeto JSON. Em sua forma mais simples, um esquema pode ser um objeto vazio {}, que valida qualquer JSON. Para torná-lo útil, definimos restrições usando palavras-chave.

A palavra-chave `type`

A palavra-chave type é a restrição mais fundamental. Ela restringe os dados JSON a um dos seguintes tipos básicos:

string: Para dados textuais.
number: Para qualquer valor numérico (inteiro ou de ponto flutuante).
integer: Apenas para números inteiros.
boolean: true ou false.
object: Para pares chave-valor.
array: Para listas ordenadas de valores.
null: Para o valor nulo.

Objetos e Propriedades

Ao definir um object, você normalmente usa a palavra-chave properties para definir o esquema para chaves específicas. A palavra-chave required é usada para listar chaves que DEVEM estar presentes nos dados.

{
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["username"]
}

Neste exemplo, "username" é obrigatório e deve ser uma string, enquanto "age" é opcional, mas deve ser um inteiro se fornecido.

Mergulho Profundo nas Palavras-chave de Validação

O JSON Schema oferece um rico conjunto de palavras-chave para ajustar suas regras de validação.

Validação Numérica

Para os tipos number e integer, você pode impor intervalos:

minimum e maximum: Limites inclusivos.
exclusiveMinimum e exclusiveMaximum: Limites exclusivos.
multipleOf: Garante que o número seja divisível por um valor específico.

Validação de Strings

As strings podem ser validadas com base no comprimento ou conteúdo:

minLength e maxLength: Controlam o comprimento da string.
pattern: Use uma Expressão Regular (Regex) para validar o formato da string (por exemplo, verificar um prefixo de ID específico).
format: Fornece validação integrada para formatos comuns como email, date-time, ipv4 e hostname.

Validação de Arrays

Os arrays podem ser validados por tamanho e unicidade do conteúdo:

minItems e maxItems: Controlam o número de elementos.
uniqueItems: Se definido como true, cada elemento no array deve ser único.
items: Define um esquema que cada elemento do array deve seguir.

Estruturando Esquemas Complexos

À medida que seus dados crescem, seus esquemas se tornam complexos. O JSON Schema fornece mecanismos para reutilização e organização.

Definições e Referências ($ref)

Em vez de repetir a mesma lógica de esquema (como um "objeto de usuário" usado em vários lugares), você pode defini-lo uma vez em uma seção definitions (ou $defs) e referenciá-lo usando a palavra-chave $ref.

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing_address": { "$ref": "#/$defs/address" },
    "shipping_address": { "$ref": "#/$defs/address" }
  }
}

Lógica Condicional

Você pode combinar esquemas usando operadores lógicos:

allOf: Os dados devem ser válidos em relação a TODOS os esquemas fornecidos.
anyOf: Os dados devem ser válidos em relação a PELO MENOS UM dos esquemas.
oneOf: Os dados devem ser válidos em relação a EXATAMENTE UM dos esquemas.
not: Os dados NÃO devem ser válidos em relação ao esquema fornecido.

Casos de Uso Práticos

O JSON Schema não é apenas um conceito teórico; ele tem aplicações práticas massivas:

1. Validação de Solicitação e Resposta de API

Ao definir esquemas para suas APIs REST ou GraphQL, você pode rejeitar automaticamente solicitações malformadas antes mesmo que elas cheguem à sua lógica de negócios. Isso reduz o código clichê e melhora a segurança, evitando ataques de injeção através de tipos de dados inesperados.

2. Arquivos de Configuração

Se a sua aplicação usa JSON para configuração, um esquema pode fornecer feedback imediato aos usuários quando eles cometem um erro de digitação ou fornecem um valor inválido, muitas vezes integrado diretamente em IDEs como o VS Code.

3. Migração e Integridade de Dados

Ao mover dados entre sistemas, você pode usar o JSON Schema para garantir que os dados que estão sendo exportados ou importados atendam aos requisitos do sistema de destino.

Exemplos: JSON Válido vs. Inválido

Vejamos um esquema para uma entrada de produto simples:

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 3 },
    "tags": { "type": "array", "uniqueItems": true }
  },
  "required": ["id", "name"]
}

JSON Válido:

{
  "id": 101,
  "name": "Mouse Sem Fio",
  "tags": ["eletrônicos", "periféricos"]
}

JSON Inválido (Faltando 'id' obrigatório):

{
  "name": "Teclado"
}

JSON Inválido (Nome muito curto):

{
  "id": 102,
  "name": "AB"
}

Ferramentas e Recursos Relacionados

Para facilitar ainda mais o trabalho com JSON, confira estas ferramentas úteis:

Conversor de JSON para TypeScript: Gere automaticamente interfaces TypeScript a partir de seus dados ou esquemas JSON, garantindo a segurança de tipos em seu código.
JSON Beautifier & Formatter: Formate e limpe rapidamente seus documentos JSON para torná-los mais fáceis de ler e depurar.

Em conclusão, o JSON Schema é uma ferramenta essencial para qualquer desenvolvedor que trabalhe com tecnologias web modernas. Ele fornece uma maneira padronizada de garantir que seus dados sejam exatamente o que você espera que sejam, reduzindo bugs e melhorando a qualidade geral da arquitetura do seu software.