O que é JSON

Os dois contêineres: objetos e arrays

Tudo no JSON é construído a partir de duas estruturas. Um objeto é um conjunto não ordenado de pares chave/valor envolto em chaves — as chaves dos pares são sempre strings, os valores podem ser qualquer valor JSON e os pares são separados por vírgulas. Um array é uma lista ordenada de valores envolta em colchetes, e seus valores podem misturar tipos à vontade.

{
  "name": "Ada Lovelace",
  "born": 1815,
  "mathematician": true
}

[
  "analytical engine",
  1843,
  null
]

Os seis tipos de dados

Quatro são escalares — string, número, booleano e null — e dois são os contêineres acima. As regras que surpreendem iniciantes são poucas, porém rígidas: strings estão sempre entre aspas duplas (aspas simples são inválidas), números não precisam de aspas e não podem ser escritos em hexadecimal, booleanos são exatamente os tokens minúsculos true e false, e null é um valor próprio que significa vazio deliberado.

Escape: o que pode viver dentro de uma string

Dentro de uma string, dois caracteres precisam ser escapados onde quer que apareçam: a aspa dupla (como ") e a barra invertida (como \). Existem mais seis escapes para caracteres de controle — \n para nova linha, \t para tabulação, \r para retorno de carro, \b para backspace, \f para form feed e \/ para a barra normal, o que é válido, mas opcional. Qualquer outro caractere pode aparecer literalmente como UTF-8, ou como um escape \uXXXX para seu ponto de código Unicode — as duas formas significam exatamente a mesma string para um parser.

"path": "C:\\Users\\ada"
"quote": "she said \"hi\""
"emoji": "\ud83d\ude00"

path:   C:\Users\ada
quote:  she said "hi"
emoji:  😀

Espaço em branco, formatação e por que a formatação existe

Entre a pontuação estrutural, o JSON permite exatamente quatro caracteres de espaço em branco: espaço, tabulação, nova linha e retorno de carro. Essa permissão é o que torna a formatação possível — o mesmo documento pode ser uma linha ilegível na rede e uma árvore indentada no seu editor, e ambos são byte a byte os mesmos dados para um parser. Formatar não muda nada no significado, razão pela qual a ferramenta formatadora é segura de rodar com qualquer payload e por que o JSON minificado é a escolha padrão para transporte.

• Sem comentários: a RFC 8259 removeu comentários deliberadamente, depois de divergências reais entre parsers. JSONC é a extensão não oficial que algumas ferramentas aceitam.
• Sem vírgulas finais: [1, 2, 3,] é inválido, por mais amigável que pareça.
• Chaves duplicadas: os parsers mantêm a primeira ou a última — a RFC 8259 deixa isso a critério das implementações, e é por isso que duplicatas são um bug mesmo onde o parser as aceita.
• Qualquer nível superior: qualquer valor pode ser um documento inteiro — um array de números é JSON completo.

Onde o JSON é usado — e onde não é

O JSON domina três territórios: corpos de requisição e resposta de APIs, configuração estruturada onde comentários não fazem falta e dados em repouso em bancos de dados de documentos. Ele divide a rede de má vontade com dois vizinhos — formatos binários como protobuf, que vencem em tamanho e velocidade quando os dois lados compartilham um schema, e YAML, que vence na facilidade de edição manual para configuração de ops. Entender JSON a fundo, portanto, não é mais uma habilidade entre tantas; é o pré-requisito para ler esses dois vizinhos, porque o YAML 1.2 faz parse de JSON e a maioria dos schemas binários se documenta com exemplos em JSON.