JSON para Desenvolvedores: Sintaxe, Validação e Erros Comuns

· 12 min de leitura

Índice

O que é JSON e Por que Importa

JSON (JavaScript Object Notation) tornou-se o padrão de facto para intercâmbio de dados na web. Apesar do nome sugerir uma conexão com JavaScript, JSON é completamente independente de linguagem e suportado por praticamente todas as linguagens de programação modernas.

Originalmente especificado por Douglas Crockford no início dos anos 2000, JSON surgiu como uma alternativa leve ao XML. Sua simplicidade e legibilidade humana o tornaram o formato perfeito para APIs, arquivos de configuração e armazenamento de dados.

Hoje, JSON alimenta tudo, desde APIs REST e bancos de dados NoSQL até arquivos de configuração e pipelines de dados. Entender JSON profundamente não é apenas útil—é essencial para o desenvolvimento de software moderno.

Dica rápida: JSON não é uma linguagem de programação ou um formato de banco de dados. É puramente um formato de serialização de dados—uma maneira de representar dados estruturados como texto.

Regras de Sintaxe JSON

A sintaxe do JSON é enganosamente simples, mas sua rigidez pega muitos desenvolvedores desprevenidos. Ao contrário dos objetos JavaScript, JSON tem tolerância zero para variações de sintaxe.

Aqui está um exemplo JSON válido que demonstra a estrutura central:

{
  "name": "RunDev",
  "version": 2,
  "features": ["formatter", "validator", "converter"],
  "config": {
    "theme": "dark",
    "autoSave": true
  },
  "deprecated": null
}

As Regras Inegociáveis

Todo documento JSON deve seguir estas regras rígidas:

Por que Tão Rígido?

A rigidez do JSON é intencional. Ao eliminar ambiguidade, JSON garante que qualquer documento JSON válido possa ser analisado de forma idêntica em todas as plataformas e linguagens. Essa previsibilidade é o que torna JSON confiável para troca de dados.

A falta de comentários é frequentemente criticada, mas força os desenvolvedores a tornar seus dados autodocumentados através de nomes de chaves claros e estrutura. Para arquivos de configuração onde comentários são necessários, considere JSONC (JSON com Comentários) ou JSON5.

Dica profissional: Use nosso Formatador JSON para corrigir automaticamente erros de sintaxe comuns e garantir que seu JSON seja válido antes da implantação.

Entendendo os Tipos de Dados JSON

JSON suporta exatamente seis tipos de dados. Este conjunto limitado mantém o formato simples enquanto cobre a maioria das necessidades de representação de dados.

Tipo Exemplo Notas
String "hello world" Deve estar entre aspas duplas. Suporta sequências de escape: \n, \t, \u0041, \", \\
Number 42, 3.14, -1, 1e10 Sem distinção entre inteiro e float. Sem hex, octal ou valores especiais como Infinity
Boolean true, false Apenas minúsculas. "true" é uma string, não um booleano
Null null Apenas minúsculas. Representa ausência intencional de valor
Array [1, "two", true] Lista ordenada. Pode conter tipos mistos (embora arrays homogêneos sejam mais claros)
Object {"key": "value"} Pares chave-valor não ordenados. Chaves devem ser strings e devem ser únicas

Strings e Sequências de Escape

Strings JSON suportam várias sequências de escape para caracteres especiais:

Strings multilinha devem usar sequências de escape—quebras de linha literais não são permitidas:

{
  "correct": "Line 1\nLine 2\nLine 3",
  "incorrect": "Line 1
Line 2
Line 3"
}

Números: O que é Permitido e O que Não É

Números JSON são mais restritivos que a maioria das linguagens de programação:

A especificação JSON não define limites de precisão, mas a maioria das implementações usa ponto flutuante de precisão dupla IEEE 754, o que significa que inteiros são seguros até 2^53 - 1 (9.007.199.254.740.991).

Dica profissional: Para inteiros grandes além do intervalo de inteiros seguros do JavaScript, considere armazená-los como strings para evitar perda de precisão durante a análise.

Objetos e Unicidade de Chaves

Embora a especificação JSON declare que as chaves de objeto devem ser únicas, ela não determina como os analisadores devem lidar com duplicatas. Diferentes implementações se comportam de forma diferente:

Melhor prática: Sempre garanta que suas chaves sejam únicas para evitar comportamento imprevisível entre diferentes analisadores.

Erros Comuns e Como Evitá-los

Até desenvolvedores experientes cometem erros de sintaxe JSON. Aqui estão os erros mais frequentes e suas correções:

Erro Errado Correto
Aspas simples {'name': 'test'} {"name": "test"}
Vírgula final {"a": 1, "b": 2,} {"a": 1, "b": 2}
Chaves sem aspas {name: "test"} {"name": "test"}
Comentários {"a": 1 // comment} Remova comentários ou use JSONC
Valor undefined {"a": undefined} {"a": null}
Zeros à esquerda {"port": 080} {"port": 80}
Novas linhas literais "line1
line2"		 "line1\nline2"
Valores de função {"fn": function(){}} Não suportado—use strings ou reestruture

A Armadilha do Objeto JavaScript

A maior fonte de erros JSON é tratá-lo como sintaxe literal de objeto JavaScript. Eles parecem similares, mas têm diferenças críticas:

// Objeto JavaScript válido
const jsObj = {
  name: 'test',        // chave sem aspas, aspas simples
  age: 30,
  active: true,
  getData: function() { return this.name; },  // funções permitidas
  // comentário permitido
};

// JSON válido (como string)
const jsonStr = `{
  "name": "test",
  "age": 30,
  "active": true
}`;

Lembre-se: JSON é um formato de dados, não código. Não pode conter funções, comentários ou lógica executável.

Problemas de Codificação de Caracteres

JSON deve ser codificado em UTF-8, UTF-16 ou UTF-32. UTF-8 é a codificação mais comum e recomendada. Cuidado com:

Dica rápida: Cole seu JSON em nosso Validador JSON para identificar instantaneamente erros de sintaxe, problemas de codificação e problemas estruturais.

Validando JSON: Ferramentas e Técnicas

A validação é crucial para detectar erros antes que causem falhas em tempo de execução. Veja como validar JSON em diferentes ambientes.

Validação por Linha de Comando

Validação rápida usando ferramentas integradas:

# Python (integrado, disponível em todos os lugares)
python3 -m json.tool data.json

# Formatar e validar
python3 -m json.tool data.json output.json

# jq (processador JSON poderoso)
jq . data.json

# jq com detalhes de erro
jq . data.json || echo "Invalid JSON"

# Node.js em uma linha
node -e "console.log(JSON.parse(require('fs').readFileSync('data.json')))"

# Usando jsonlint (instalar via npm)
jsonlint data.json

Validação Programática

Valide JSON no código da sua aplicação:

// JavaScript/Node.js
function isValidJSON(str) {
  try {
    JSON.parse(str);
    return true;
  } catch (e) {
    console.error('JSON Error:', e.message);
    return false;
  }
}

# Python
import json

def is_valid_json(json_str):
    try:
        json.loads(json_str)
        return True
    except json.JSONDecodeError as e:
        print(f'JSON Error: {e}')
        return False

// Go
import "encoding/json"

func isValidJSON(data []byte) bool {
    var js json.RawMessage
    return json.Unmarshal(data, &js) == nil
}

Validação de Schema

A validação de sintaxe apenas verifica se o JSON está bem formado. A validação de schema garante que a estrutura de dados e os tipos correspondam aos seus requisitos.

JSON Schema é o padrão para definir estrutura JSON:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "email"]
}

Bibliotecas populares de validação de schema:

Dica profissional: Use nosso Validador de JSON Schema para testar seus schemas contra dados de exemplo antes de implementá-los no código.

Ferramentas de Validação Online

Para verificações rápidas durante o desenvolvimento:

Melhores Práticas de Análise e Serialização

A análise converte texto JSON em estruturas de dados nativas. A serialização faz o inverso. Ambas as operações têm implicações de desempenho e segurança.

Práticas Seguras de Análise

Sempre envolva a análise JSON em tratamento de erros:

// JavaScript - Análise básica
try {
  const data = JSON.parse(jsonString);
  // Use data
} catch (error) {
  console.error('Failed to parse JSON:', error.message);
  // Trate o erro apropriadamente
}

// JavaScript - Com função reviver
const data = JSON.parse(jsonString, (key, value) => {
  // Transforme datas de strings
  if (key.endsWith('Date') && typeof value === 'string') {
    return new Date(value);
  }
  return value;
});

Melhores Práticas de Serialização

Controle como objetos são convertidos para JSON:

// JavaScript - Serialização básica
const json = JSON.stringify(data);

// Formatação bonita com indentação
const json = JSON.stringify(data, null, 2);

// Serialização personalizada com replacer
const json = JSON.stringify(data, (key, value) => {
  // Remova campos sensíveis
  if (key === 'password' || key === 'apiKey') {
    return undefined;
  }
  // Converta BigInt para string
  if (typeof value === 'bigint'