JSON vs JSON5 vs JSONC
Resumo: Superconjuntos estritos em ordem: JSONC adiciona comentários; JSON5 adiciona aspas simples, chaves sem aspas, vírgulas finais e números hexadecimais. Escolher errado quebra uma API, não o seu editor.
Resumo da ópera: use JSON padrão sempre que os dados cruzarem uma fronteira de sistema, e use JSONC apenas para configuração local que humanos editam; recorra ao JSON5 quando precisar de aspas simples, vírgulas finais ou chaves sem aspas, mas confirme primeiro que o carregador o suporta.
Em uma linha: JSONC é JSON mais comentários; JSON5 é JSON mais hábitos JavaScript.
Matriz de recursos
| Recurso | JSON | JSONC | JSON5 |
|---|---|---|---|
| Strings com aspas duplas | ✅ | ✅ | ✅ |
| Strings com aspas simples | ❌ | ❌ | ✅ |
| Chaves sem aspas | ❌ | ❌ | ✅ |
Comentários de linha // |
❌ | ✅ | ✅ |
Comentários de bloco /* */ |
❌ | ✅ | ✅ |
| Vírgulas finais | ❌ | ❌ | ✅ |
Números hexadecimais 0xFF |
❌ | ❌ | ✅ |
Infinity / NaN |
❌ | ❌ | ✅ |
| Strings multilinha | ❌ | ❌ | ✅ |
| Legível por analisadores padrão | ✅ | ❌ | ❌ |
Observe que o JSONC resolve apenas comentários. Muita gente presume que "JSON que permite comentários" também permite vírgulas finais; o tsconfig.json ainda falha com uma.
Para que serve cada um
JSON — intercâmbio. APIs, filas, colunas JSON de banco de dados, logs. Qualquer coisa de máquina para máquina.
JSONC — configuração de editor. O VS Code analisa esses arquivos ele mesmo, então JSON.parse nunca os vê. Não há RFC; é uma convenção de fato liderada pela Microsoft.
JSON5 — um superconjunto leniente para humanos. O objetivo era "configuração que parece um literal de objeto JavaScript". Mais adequado a arquivos .json5 carregados por ferramentas de build; a sintaxe mais ampla e o suporte de ferramentas mais estreito.
Escolhendo
| Situação | Escolha |
|---|---|
| Corpos de requisição ou resposta | JSON, sem alternativa |
| Colunas JSON no MySQL / PostgreSQL | JSON, suas funções não aceitam outra coisa |
| Configuração de projeto que precisa de explicação | JSONC se suportado, caso contrário YAML |
| Você quer frouxidão no estilo JS | JSON5, após confirmar que o carregador suporta |
| Não-engenheiros vão editar | YAML, a indentação vence as chaves |
Uma armadilha fácil
Analisar um arquivo JSONC como JSON estrito produz um erro que aponta para o comentário:
SyntaxError: Unexpected token / in JSON at position 42
Antes de excluir o comentário, verifique se o arquivo deveria ser JSONC. Exclua-o e você ainda pode esbarrar em uma vírgula final duas linhas depois.
Perguntas frequentes
Como devo escolher entre JSONC e JSON5?
Use JSONC quando comentários forem a única coisa de que você precisa: ele adiciona // e /* */ em cima do JSON, e settings.json e tsconfig.json do VS Code o usam. Use JSON5 quando você também quiser aspas simples, chaves sem aspas, vírgulas finais, números hexadecimais ou strings multilinha. Ambos dependem do carregador, então confirme que a ferramenta que lê o arquivo o suporta.
Por que um arquivo JSONC não pode ser lido como JSON padrão?
JSONC é uma convenção de fato, não uma RFC separada, então analisadores padrão rejeitam comentários. JSON.parse em tal arquivo lança Unexpected token /, apontando para o comentário em vez dos dados. Só configuração lida por um editor ou por um analisador dedicado deve ser escrita como JSONC.
Devo enviar um arquivo JSON5 para uma API?
Não. APIs, colunas JSON de banco de dados e filas analisam JSON estrito, então as aspas simples, chaves sem aspas e vírgulas finais do JSON5 são rejeitadas. JSON5 é para configuração local editada por humanos; converta-o para JSON padrão antes que cruze uma fronteira de sistema.