JSON é onipresente no desenvolvimento web moderno. Domine as melhores práticas e evite erros comuns.

O Que É JSON?

JavaScript Object Notation é um formato leve de intercâmbio de dados, fácil para humanos lerem e escreverem, e fácil para máquinas parsearem e gerarem.

Estrutura Básica

{
  "string": "texto",
  "numero": 42,
  "booleano": true,
  "nulo": null,
  "array": [1, 2, 3],
  "objeto": {
    "chave": "valor"
  }
}

Tipos de Dados JSON

6 Tipos Permitidos

String: "texto" (sempre com aspas duplas)
Number: 42, 3.14, -10, 1e5
Boolean: true ou false
Null: null
Object: {"chave": "valor"}
Array: [1, 2, 3]

❌ Não Permitidos

Funções
Dates (use string ISO ou timestamp)
undefined
Comentários
Aspas simples
Trailing commas

Boas Práticas de Nomenclatura

✅ Use camelCase

{
  "firstName": "João",
  "lastName": "Silva",
  "dateOfBirth": "1990-01-01"
}

Ou snake_case (seja consistente!)

{
  "first_name": "João",
  "last_name": "Silva",
  "date_of_birth": "1990-01-01"
}

❌ Evite Misturar

{
  "firstName": "João",
  "last_name": "Silva"  // Inconsistente!
}

Formatação e Legibilidade

✅ JSON Formatado (Desenvolvimento)

{
  "usuario": {
    "id": 1,
    "nome": "João Silva",
    "email": "joao@email.com",
    "ativo": true
  }
}

✅ JSON Minificado (Produção)

{"usuario":{"id":1,"nome":"João Silva","email":"joao@email.com","ativo":true}}

Economia: ~40% de redução no tamanho!

Use nosso Formatador JSON para converter entre os dois.

Validação de JSON

Erros Comuns de Sintaxe

1. Vírgula Final (Trailing Comma)

❌ {
  "nome": "João",
  "idade": 30,  // Vírgula extra!
}

✅ {
  "nome": "João",
  "idade": 30
}

2. Aspas Simples

❌ {
  'nome': 'João'  // Aspas simples não funcionam!
}

✅ {
  "nome": "João"
}

3. Chaves Sem Aspas

❌ {
  nome: "João"  // Chave precisa de aspas!
}

✅ {
  "nome": "João"
}

4. Comentários

❌ {
  // Isto é um comentário
  "nome": "João"
}

✅ {
  "_comment": "Use chaves para comentários, se necessário",
  "nome": "João"
}

5. Valores Undefined

❌ {
  "nome": "João",
  "idade": undefined
}

✅ {
  "nome": "João",
  "idade": null
}

Trabalhando com Datas

❌ Formato Incorreto

{
  "data": new Date("2025-01-15")  // Não funciona!
}

✅ ISO 8601 (Recomendado)

{
  "data": "2025-01-15T14:30:00Z",
  "dataSimples": "2025-01-15"
}

✅ Unix Timestamp

{
  "timestamp": 1705329000
}

JavaScript:

// ISO para Date
const data = new Date("2025-01-15T14:30:00Z");

// Date para ISO
const iso = new Date().toISOString();

// Timestamp para Date
const data = new Date(1705329000 * 1000);

Estruturas de Dados Eficientes

Arrays vs Objetos

Use Arrays para Listas

{
  "usuarios": [
    {"id": 1, "nome": "João"},
    {"id": 2, "nome": "Maria"}
  ]
}

Use Objetos para Lookups

{
  "usuarios": {
    "1": {"nome": "João"},
    "2": {"nome": "Maria"}
  }
}

Vantagem: Acesso O(1) por ID!

Normalização de Dados

❌ Dados Denormalizados (Redundância)

{
  "posts": [
    {
      "id": 1,
      "titulo": "Post 1",
      "autor": {
        "id": 1,
        "nome": "João",
        "email": "joao@email.com"
      }
    },
    {
      "id": 2,
      "titulo": "Post 2",
      "autor": {
        "id": 1,
        "nome": "João",  // Repetido!
        "email": "joao@email.com"
      }
    }
  ]
}

✅ Dados Normalizados

{
  "posts": [
    {"id": 1, "titulo": "Post 1", "autorId": 1},
    {"id": 2, "titulo": "Post 2", "autorId": 1}
  ],
  "autores": {
    "1": {"id": 1, "nome": "João", "email": "joao@email.com"}
  }
}

APIs RESTful e JSON

Respostas Consistentes

✅ Estrutura Padrão de Sucesso

{
  "success": true,
  "data": {
    "id": 1,
    "nome": "João"
  },
  "message": "Usuário encontrado"
}

✅ Estrutura Padrão de Erro

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "Usuário não encontrado",
    "details": {
      "userId": 999
    }
  }
}

Paginação

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}

Versionamento

{
  "apiVersion": "v1",
  "data": {...}
}

Segurança

❌ Nunca Exponha Dados Sensíveis

❌ {
  "usuario": {
    "nome": "João",
    "senha": "123456",  // NUNCA!
    "cartaoCredito": "1234-5678-9012-3456"
  }
}

✅ Filtre Dados no Backend

{
  "usuario": {
    "id": 1,
    "nome": "João",
    "email": "j***@email.com"  // Parcialmente ofuscado
  }
}

Escape de Strings

{
  "html": "<script>alert('xss')</script>",  // Perigoso!
  "escapado": "&lt;script&gt;alert('xss')&lt;/script&gt;"
}

Performance e Otimização

1. Minifique JSON em Produção

Remove espaços em branco
Remove quebras de linha
Reduz ~40% do tamanho

2. Use Compressão (gzip/brotli)

JSON original: 100 KB
Minificado: 60 KB (-40%)
Gzipped: 15 KB (-85%)
Brotli: 12 KB (-88%)

3. Carregamento Preguiçoso (Lazy Loading)

Em vez de:

{
  "usuario": {
    "id": 1,
    "nome": "João",
    "posts": [/* 1000 posts */],
    "comentarios": [/* 5000 comentarios */]
  }
}

Use:

{
  "usuario": {
    "id": 1,
    "nome": "João",
    "postsUrl": "/api/usuarios/1/posts",
    "comentariosUrl": "/api/usuarios/1/comentarios"
  }
}

4. Campos Parciais (Sparse Fieldsets)

GET /api/usuarios?fields=id,nome

Retorna apenas campos solicitados:

{
  "id": 1,
  "nome": "João"
}

Debugging de JSON

Ferramentas

JSONLint - Validador online
jq - Processador de JSON em linha de comando
Nosso Formatador - Formatador JSON

Técnicas

1. Validação no Navegador

try {
  JSON.parse(jsonString);
  console.log("JSON válido!");
} catch (e) {
  console.error("Erro:", e.message);
}

2. Pretty Print

const obj = {nome: "João", idade: 30};
console.log(JSON.stringify(obj, null, 2));

Saída:

{
  "nome": "João",
  "idade": 30
}

3. jq (Linha de Comando)

# Formatar
echo '{"nome":"João"}' | jq

# Filtrar
jq '.usuarios[] | select(.ativo == true)' dados.json

# Extrair campo
jq '.nome' dados.json

JSON Schema (Validação Avançada)

Definir Esquema

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

Validar Dados

// Usando biblioteca Ajv
const Ajv = require('ajv');
const ajv = new Ajv();

const validate = ajv.compile(schema);
const valid = validate(data);

if (!valid) console.log(validate.errors);

Alternativas ao JSON

YAML

Mais legível
Suporta comentários
Usado em configs (Docker, Kubernetes)

TOML

Muito simples
Usado em Rust (Cargo.toml)

Protocol Buffers / MessagePack

Binário (não texto)
Muito mais rápido e menor
Menos legível

Quando usar JSON: APIs REST, configs web, intercâmbio de dados universal

Checklist de Boas Práticas

Conclusão

JSON é simples, mas há muitas armadilhas. Seguindo estas práticas:

✅ Evita erros comuns
✅ Melhora performance
✅ Facilita manutenção
✅ Aumenta segurança

Ferramenta útil: Formatador e Validador JSON