JSON com Comentarios

JSONC (JSON with Comments) estende o JSON padrao para permitir comentarios estilo JavaScript. Muitas ferramentas de desenvolvimento usam JSONC para arquivos de configuracao onde comentarios ajudam a documentar configuracoes. Este parser remove comentarios para produzir JSON valido preservando a estrutura de dados.

Especificacoes

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Casos de Uso Comuns

• Analisar tsconfig.json e jsconfig.json para projetos TypeScript/JavaScript
• Ler settings.json e configuracao de extensoes do VS Code
• Processar arquivos de configuracao wrangler.jsonc do Cloudflare
• Editar configuracoes ESLint, Prettier e outras ferramentas com documentacao inline

Funcionalidades

• Analisar comentarios de linha unica (// comentario)
• Analisar comentarios de multiplas linhas (/* comentario */)
• Tratar virgulas finais (comuns em arquivos JSONC)
• Remover comentarios para produzir saida JSON valida
• Todos os recursos do Parser JSON padrao (visualizacao em arvore, conversao)

Exemplos

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Dicas

• VS Code, TypeScript e muitas ferramentas modernas suportam JSONC nativamente.
• Ao compartilhar configuracao, considere se as ferramentas dos destinatarios suportam comentarios.
• Converta para JSON padrao removendo comentarios quando ferramentas exigem JSON estrito.

Entendendo JSON com Comentarios

JSONC (JSON with Comments) e uma extensao do JSON padrao que permite comentarios de linha unica (//) e de multiplas linhas (/* */) estilo JavaScript, assim como virgulas finais apos o ultimo elemento em arrays e objetos. Embora nao seja um padrao oficial, JSONC se tornou o formato de fato para arquivos de configuracao voltados ao desenvolvedor onde documentacao inline melhora a manutenibilidade.

A Microsoft popularizou JSONC atraves do Visual Studio Code, que o usa para settings.json, keybindings.json, launch.json e extensions.json. O tsconfig.json do TypeScript e o jsconfig.json do JavaScript sao arquivos JSONC, assim como muitas configuracoes ESLint, Prettier e Babel ao usar a extensao .json. O wrangler.jsonc do Cloudflare explicitamente usa a extensao .jsonc para sinalizar suporte a comentarios.

A vantagem principal do JSONC sobre JSON simples e a documentacao. Arquivos de configuracao frequentemente contem configuracoes cujo proposito nao e obvio apenas pelo nome da chave. Comentarios permitem que desenvolvedores expliquem por que uma configuracao existe, quais sao os valores validos e quais sao as consequencias de mudancas. Virgulas finais reduzem ruido no controle de versao permitindo que o ultimo elemento tenha o mesmo formato que todos os outros, entao adicionar um novo item mostra apenas uma linha alterada em um diff em vez de duas.

Nos bastidores, parsers JSONC funcionam removendo comentarios e virgulas finais antes de passar o resultado para um parser JSON padrao. Isso significa que o modelo de dados e identico ao JSON — comentarios sao metadados para humanos, nao dados para programas. Ao converter JSONC para JSON para ferramentas que exigem conformidade JSON estrita, os comentarios sao simplesmente removidos. A biblioteca node-jsonc-parser da Microsoft, usada no VS Code, e a implementacao de referencia para parse JSONC.

JSONC nao e um padrao oficial definido por nenhuma RFC ou especificacao ECMA. E uma convencao popularizada pela Microsoft atraves do VS Code e TypeScript, com comportamento bem definido pela biblioteca jsonc-parser que serve como implementacao de referencia. Outras ferramentas que suportam JSONC — ESLint, Prettier e varios editores — seguem as mesmas convencoes para comentarios de linha unica, comentarios de multiplas linhas e virgulas finais. Arquivos JSONC comuns incluem tsconfig.json e jsconfig.json (TypeScript/JavaScript), arquivos de configuracao do VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) e varias outras configuracoes de ferramentas. Qualquer arquivo JSON editado principalmente por desenvolvedores que poderia se beneficiar de comentarios provavelmente suporta JSONC.

JSONC deve ser usado apenas para arquivos de configuracao lidos por ferramentas com suporte explicito a JSONC. Respostas de API, armazenamento de dados e comunicacao entre servicos devem sempre usar JSON padrao, pois a maioria dos parsers JSON rejeitara comentarios como erros de sintaxe. Para processar um arquivo de configuracao JSONC programaticamente com um parser JSON padrao, remova os comentarios primeiro usando uma biblioteca com suporte a JSONC.

JSONC e mais conservador que JSON5, que e um superconjunto mais extenso de JSON. Enquanto JSONC adiciona apenas comentarios e virgulas finais, JSON5 tambem permite strings com aspas simples, chaves de objeto sem aspas, numeros hexadecimais, pontos decimais no inicio e fim, Infinity e NaN, e strings multi-linha. JSONC tem suporte mais amplo de ferramentas no ecossistema de desenvolvedores, enquanto JSON5 e usado em arquivos de configuracao especificos como babel.config.json5 do Babel, mas tem adocao mais restrita no geral.