Cola de sintaxe JSON

Os seis caracteres estruturais

Seis caracteres de pontuação carregam toda a estrutura do JSON: as chaves { } que envolvem objetos, os colchetes [ ] que envolvem arrays, os dois-pontos : que separam uma chave de seu valor e a vírgula , que separa pares dentro de um objeto ou valores dentro de um array. Nada mais na gramática faz trabalho estrutural — todo outro caractere em um documento ou está dentro de uma string ou é um dos quatro caracteres de espaço em branco. Uma vírgula é estritamente um separador: ela pode aparecer entre dois itens, nunca antes de uma chave ou colchete de fechamento.

{"name":"Ada","tags":["math","pioneer"]}

{"name":"Ada","tags":["math","pioneer"],}

Espaço em branco: exatamente quatro caracteres

Fora de strings, o JSON permite exatamente quatro caracteres de espaço em branco: o espaço (U+0020), a tabulação horizontal (U+0009), o avanço de linha (U+000A) e o retorno de carro (U+000D). Qualquer outra coisa — tabulação vertical, avanço de formulário, espaço sem quebra, uma marca de ordem de byte — é um erro de sintaxe, mesmo que muitos editores renderizem esses caracteres de forma invisível. É por isso que JSON colado de um processador de texto com tanta frequência falha na validação: o documento parece limpo na tela e contém caracteres dos quais a gramática nunca ouviu falar.

O espaço em branco também é o que torna a formatação possível. Como a gramática ignora esses quatro caracteres entre tokens, o mesmo documento pode ser uma linha longa na rede e uma árvore indentada no seu editor, e as duas formas são semanticamente idênticas — nenhum parser consegue distingui-las depois de ler.

{"a":1,"b":[2,3]}

{
  "a": 1,
  "b": [
    2,
    3
  ]
}

Strings: aspas duplas e os nove escapes

Uma string do JSON é envolvida por aspas duplas — nunca aspas simples. Dentro, a barra invertida \ introduz um escape, e o RFC 8259 define exatamente nove escapes de dois caracteres: dois são obrigatórios, \" para uma aspa dupla literal e \\ para uma barra invertida literal, porque esses dois caracteres, de outro modo, encerrariam ou corromperiam a string. Mais seis são abreviações opcionais — \/ para a barra normal e \b \f \n \r \t para os cinco caracteres de controle que aparecem com mais frequência em texto. A nona forma é \uXXXX, que escreve qualquer ponto de código Unicode pelo seu número hexadecimal de quatro dígitos.

Todo caractere fora do conjunto de escapes pode aparecer literalmente como UTF-8, e as duas formas são equivalentes: um parser entrega a string idêntica de qualquer jeito. Escapar é grafia, não dado — um ponto que o guia de escape desenvolve em profundidade.

"quote": "she said \"hi\""
"path": "C:\\Users\\ada"
"e-acute": "\u00e9"

quote:   she said "hi"
path:    C:\Users\ada
e-acute: é

Números: ECMAScript, menos as extensões

Um número é um inteiro ou decimal em notação simples, com um expoente opcional. O RFC 8259 adota a gramática de números do ECMAScript e remove as extensões dela: nada de hexadecimal, octal, zeros à esquerda, sinal de mais à esquerda ou ponto final solto. Um expoente usa e ou E com um sinal opcional, e o único sinal com que um número pode começar é o hífen comum. NaN, Infinity e -Infinity não são JSON — linguagens que têm essas constantes escrevem null no lugar delas, por convenção.

A precisão é deliberadamente deixada para as implementações: a gramática não diz nada sobre quantos dígitos um parser precisa honrar, então números muito longos podem chegar alterados em silêncio. Produtores interoperáveis mantêm os inteiros dentro do intervalo que a plataforma de destino representa exatamente — para os doubles IEEE 754 por trás do JavaScript, isso é até 2^53 − 1.

Os três literais e as cinco rejeições clássicas

Três tokens puros completam o conjunto de valores: true, false e null. São minúsculos e sem aspas — True, FALSE e None são erros de sintaxe, não capitalização criativa. Ao redor deles, a gramática traça cinco linhas que explicam quase todo documento rejeitado lá fora:

• Sem comentários. O RFC 8259 não tem sintaxe de comentário; // ou /* */ em qualquer lugar é um erro de sintaxe. Anote com uma chave irmã como "_comment" quando o formato estiver sob seu controle.
• Sem vírgulas finais. [1, 2, 3,] e {"a":1,} são inválidos, por mais simpáticos que pareçam — a vírgula é um separador, e não pode separar um item de nada.
• Sem aspas simples e sem chaves sem aspas. {name:'ada'} é JSON inválido; {"name":"ada"} é a única grafia da gramática.
• Sem chaves duplicadas — oficialmente. A gramática permite que um nome apareça duas vezes, mas o RFC 8259 §4 deixa para as implementações decidir qual valor vence, então um documento que dependa de duplicatas não tem significado definido.
• Qualquer valor de nível superior. Desde o RFC 8259, um documento inteiro pode ser uma string, número, booleano ou null puro — a regra de só objetos e arrays do RFC 4627 caiu fora, e "hello" ou 42 são documentos JSON completos.

Codificação: UTF-8 e as regras no nível de bytes

O RFC 8259 §8.1 fixa a codificação de bytes: texto JSON trocado entre sistemas que não fazem parte de um ecossistema fechado precisa estar codificado em UTF-8. Não existe JSON em UTF-16 ou UTF-32 na rede aberta, e produtores não devem antepor uma marca de ordem de byte — um parser pode ignorar um BOM à esquerda em vez de errar, mas nada em conformidade emite um. Repare como as camadas se separam: escapar com \uXXXX é uma escolha de notação dentro de strings individuais, enquanto UTF-8 é uma propriedade do documento inteiro, e as duas resolvem problemas diferentes.

Isso fecha a gramática. O jeito mais rápido de fixar essas regras é rodar seus próprios documentos contra elas — formate um payload real, quebre uma regra por vez e leia cada erro do validador. Dez minutos de falha de propósito ensinam mais do que mais uma passada por esta página.