De JSON5 a JSONC: como usar formatos JSON mais permissivos

Quando o JSON estrito faz você depurar até de madrugada por uma vírgula faltando, talvez seja hora de conhecer seus primos mais tolerantes — JSON5 e JSON com Comentários (JSONC).

O que é JSON5?

JSON5 é uma extensão do JSON que incorpora características do ECMAScript 5.1: chaves sem aspas, vírgulas finais, strings com aspas simples, comentários e números hexadecimais. É mantido pela comunidade e projetado para que arquivos de configuração escritos à mão sejam mais legíveis e tolerantes do que o JSON estrito.

O que é JSONC?

JSONC (JSON with Comments) é uma extensão mínima do JSON padrão que adiciona suporte para comentários de uma linha (//) e multilinha (/* */), além de vírgulas finais. Mantido pela Microsoft, é o formato nativo da configuração do VS Code, tsconfig.json e outros arquivos de configuração do TypeScript.

Por que precisamos de JSON “permissivo”

Gargalos de legibilidade: O JSON padrão proíbe comentários, vírgulas finais, aspas simples, etc., o que prejudica a clareza em configurações e demos.
Dor no trabalho em equipe: Arquivos JSON massivos sem notas em linha são difíceis de manter; uma edição menor pode quebrar o arquivo inteiro.
Realidades de DevOps: Os pipelines de Kubernetes e CI/CD frequentemente mesclam ou geram JSON em tempo real; a sintaxe permissiva reduz as correções manuais.

JSON5 vs. JSONC em um olhar

Característica	JSON (estrito)	JSON5	JSONC
Comentários de linha `//`	Não	Sim	Sim
Comentários de bloco `/* */`	Não	Sim	Sim
Vírgulas finais	Não	Sim	Sim
Strings com aspas simples	Não	Sim	Não
Chaves sem aspas	Não	Sim	Não
Sinais numéricos `+` / `-`	Não	Sim	Não
Números hex / binário	Não	Sim	Não
Mantenedores da spec	ECMA	Comunidade (A. Rauschmayer)	Microsoft / VS Code

Em uma frase: JSON5 se parece com um objeto literal de JavaScript, enquanto JSONC é simplesmente JSON padrão mais comentários.

Exemplos de sintaxe

JSON puro (estrito)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

Exemplo JSON5

// Configuração do projeto
{
  name: 'Go Tools',      // aspas simples e chaves sem aspas
  features: [
    'Base64',
    'JSON Formatter',    // vírgula final
  ],
  version: 1.0,          // número não string permitido
}

Exemplo JSONC

{
  // Nome do projeto
  "name": "Go Tools",
  // Lista de funcionalidades
  "features": [
    "Base64",
    "JSON Formatter", // vírgula final
  ]
}

Suporte de formatação e análise

Cenário	JSON5	JSONC	Libs / ferramentas recomendadas
Navegador	Polyfill `JSON5.parse()`, Prettier com parser `json5` integrado (>= v1.13)	Suporte nativo de `settings.json` do VS Code	—
Node.js	Pacote npm `json5`	`comment-json`, `jsonc-parser`	Suportam formatação CLI e análise AST
IDE	Extensões para VS Code, WebStorm	VS Code nativo, plugin do WebStorm	Prettier pode unificar a formatação
CI / Lint	`eslint-plugin-json5`	`eslint-plugin-jsonc`	Integrar com Husky e lint-staged
Ferramenta online	Go Tools JSON Formatter (embeleza e valida JSON5/JSONC)	Igual	JSON Formatter

Formatação rápida no VS Code

Adicione ao settings.json:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Depois pressione Alt + Shift + F para embelezar qualquer arquivo JSONC.

Arquivos de configuração do mundo real

JSON5 e JSONC já são amplamente usados nos arquivos de configuração que você encontra diariamente. Aqui estão exemplos concretos:

TypeScript (tsconfig.json — JSONC)

{
  // O modo estrito detecta mais erros em tempo de compilação
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Alias de caminhos para importações mais limpas
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

O tsconfig.json do TypeScript usa JSONC nativamente — comentários e vírgulas finais funcionam sem configuração adicional. Este é um dos arquivos JSONC mais comuns em qualquer projeto JavaScript/TypeScript.

Configuração Plana do ESLint (eslint.config.json — JSONC)

{
  "rules": {
    // Avisar sobre console.log, mas permitir console.error
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
  }
}

Babel (babel.config.json5 — JSON5)

{
  // Aspas simples e chaves sem aspas melhoram a legibilidade
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Deixar o bundler lidar com os módulos
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

Configuração do Workspace do VS Code (.vscode/settings.json — JSONC)

{
  // Preferências do editor
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Sobrescritas por linguagem
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

Dicas práticas e avisos

1. Converta antes de produção

Os navegadores ainda requerem JSON estrito para JSON.parse. Use ferramentas no passo de build para remover comentários e vírgulas finais:

// Script de build Node.js: converte config JSON5 para JSON estrito
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';

const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));

Para bundlers, use rollup-plugin-json5 ou vite-plugin-json5 para lidar com a conversão automaticamente durante o build.

2. Segurança e confiabilidade

A permissividade pode ocultar campos indesejados. Valide sempre a configuração com JSON Schema ou zod antes de consumi-la:

// Valida a forma da config com zod após analisar
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Lança exceção se inválido

3. Convenções da equipe

Declare no README que *.json5 é apenas para configurações; os pacotes publicados devem ser distribuídos com .json estrito.
Padronize as regras do Prettier para evitar diffs ruidosos.
Use .editorconfig para aplicar indentação consistente em arquivos JSON, JSON5 e JSONC.

4. Performance

Analisar JSON5/JSONC adiciona dependências e um leve overhead — está tudo bem para CLI e ferramentas de desenvolvimento, mas meça em produção. O pacote npm json5 pesa ~8 KB minificado, e a análise é aproximadamente 2-5x mais lenta que o JSON.parse nativo. Para arquivos de configuração carregados uma vez na inicialização, isso é insignificante. Para caminhos críticos de performance que analisam milhares de objetos por segundo, fique com JSON estrito.

Perguntas frequentes

Qual é a diferença entre JSON5 e JSONC?

JSON5 estende JSON com sintaxe semelhante a JavaScript: chaves sem aspas, vírgulas finais, comentários de uma linha e de bloco, números hexadecimais e strings multilinha. JSONC é mais simples — apenas adiciona comentários de uma linha (//) e de bloco (/* */) ao JSON padrão. Escolha JSONC para arquivos de configuração onde comentários são suficientes; escolha JSON5 quando precisar de uma sintaxe mais rica.

Posso usar JSON5 ou JSONC em APIs de produção?

Não — JSON5 e JSONC são projetados para arquivos de configuração, não para troca de dados. APIs devem usar JSON padrão (RFC 8259) para máxima interoperabilidade. Reserve JSON5/JSONC para arquivos de configuração locais como tsconfig.json, .vscode/settings.json ou configuração de ambiente onde a legibilidade humana importa mais do que a análise automática.

O VS Code suporta JSON5 nativamente?

O VS Code suporta JSONC nativamente (seus próprios arquivos de configuração usam JSONC), mas não suporta JSON5 de fábrica. Para JSON5, instale uma extensão dedicada como “JSON5 syntax” do marketplace do VS Code. Você também pode associar arquivos .json5 com o modo de linguagem JSON5 nas suas configurações.

Como converto JSON5 para JSON padrão?

Use o pacote npm json5: JSON5.parse() lê JSON5, depois JSON.stringify() produz JSON padrão. Para uso em CLI, execute npx json5 < input.json5 > output.json. Ferramentas online como nosso JSON Formatter também podem validar a saída convertida para garantir a correção.

JSONC é o mesmo que JSON com Comentários?

Sim — JSONC significa “JSON with Comments” (JSON com Comentários) e é o formato utilizado pelo VS Code, TypeScript (tsconfig.json) e outras ferramentas da Microsoft. Segue a spec JSON padrão com a única adição de comentários // e /* */. Os analisadores removem os comentários antes de processar, então a estrutura de dados resultante é idêntica ao JSON padrão.

Para mais ferramentas de desenvolvimento no navegador, incluindo codificação Base64, geração de hashes e conversão de timestamps, consulte nosso Guia essencial de ferramentas para desenvolvedores.

Conclusão

Equilibrar legibilidade e rigor é uma luta clássica do desenvolvimento. JSON5 e JSONC melhoram a experiência de escrita, e com o pipeline de build e validação correto, você pode aproveitar as vantagens do “JSON permissivo” com segurança.

De JSON5 a JSONC: Um Guia de Formato JSON Mais Permissivo