O JSON não tem comentários porque quem o projetou tirou eles de propósito. Douglas Crockford, que formalizou a especificação do JSON no início dos anos 2000, explicou depois o motivo com as próprias palavras: ele tinha visto gente enfiando diretivas de parsing dentro de comentários — instruções pensadas para um leitor específico do arquivo, escondidas dentro do que devia ser um dado simples e intercambiável. Assim que isso começa a acontecer, dois programas lendo o mesmo documento podem discordar de forma legítima sobre o que ele significa, que é exatamente a única coisa que um formato de troca de dados não pode se dar ao luxo de permitir. Tirar a sintaxe de comentários por completo foi a solução direta: sem lugar nenhum para colocar uma diretiva, ninguém consegue esconder uma.
O que Crockford realmente disse, e o que ele sugeriu no lugar
A explicação vem de uma publicação pública dele, depois citada em vários lugares: "Eu tirei os comentários do JSON porque vi que as pessoas os usavam para carregar diretivas de parsing, uma prática que teria destruído a interoperabilidade." A sugestão que ele deu depois foi pragmática, não absoluta — comentários são bem-vindos, desde que nunca cheguem ao parser: "Se você quer comentários no seu JSON, fique à vontade — só tire eles antes de entregar o arquivo para o seu parser." É a filosofia inteira em uma frase só. Um passo de build, um pré-processador, um buscar e substituir num editor de texto — qualquer coisa que remova o comentário antes de JSON.parse ver o arquivo mantém a única garantia do formato: todo parser conforme, em qualquer linguagem, lê os mesmos bytes do mesmo jeito.
Dois dialetos tamparam essa lacuna, e não são a mesma coisa
JSON5 é o maior dos dois. É um superconjunto do JSON construído também para ser um subconjunto viável do ECMAScript 5, então além de comentários ele permite strings entre aspas simples, chaves de objeto sem aspas, uma vírgula final, números hexadecimais e números com ponto decimal solto no início ou no fim. É genuinamente popular — em 2022 o próprio projeto reportou mais de 65 milhões de downloads semanais no npm, o que o colocava entre os 0,1% de pacotes mais dependidos, com Chromium, Next.js e Babel entre as ferramentas que leem arquivos de configuração escritos nele.
JSONC — JSON com comentários — é mais restrito. Mantém a gramática do JSON quase inteira e acrescenta exatamente duas coisas: comentários // e /* */, mais uma vírgula final que a maioria dos leitores de JSONC tolera com um aviso em vez de um erro. Não é bem um formato de uso geral, é mais um estilo da casa: existe porque o VS Code precisava de um lugar para colocar as próprias configurações com notas, e ficou restrito de propósito.
Nenhum dos dois é JSON. Um arquivo escrito em qualquer um deles falha assim que chega no JSON.parse, ou em qualquer outro leitor rigoroso — incluindo o deste site.
Quais dos seus arquivos de configuração são secretamente qual dialeto
É aqui que a diferença deixa de ser curiosidade e passa a explicar mensagens de erro. O package.json é lido pelo npm com um parser rigoroso: um // em qualquer lugar dele é erro de sintaxe, ponto final, sem exceção para "só dessa vez." O tsconfig.json é o caso oposto no mesmo ecossistema — o compilador do TypeScript o parseia como JSONC, então comentários de linha e de bloco e uma vírgula final não são só tolerados, são normais, e a maioria dos editores destaca a sintaxe do arquivo de acordo. O settings.json, o tasks.json e o launch.json do próprio VS Code usam o mesmo modo JSONC. Três arquivos que terminam todos em .json, morando no mesmo repositório, obedecendo três regras diferentes dependendo inteiramente de qual programa vai abri-los a seguir.
A extensão nunca te diz qual regra vale. O único jeito confiável de descobrir é checar o que realmente lê o arquivo — e se você não tem certeza, assuma JSON rigoroso e deixe os comentários de fora, porque essa suposição nunca está errada.
O que acontece quando você cola um arquivo com comentários aqui
O formatador de JSON deste site é rigoroso de propósito, igual ao JSON.parse. Cole um arquivo com uma linha // e ele vai reportar um erro de sintaxe na posição onde o comentário começa, do mesmo jeito que reportaria uma vírgula final perdida. Isso não é um bug para relatar — um formatador que aceitasse JSON5 ou JSONC caladinho estaria mentindo sobre o que o seu destino real vai fazer com o arquivo, e a única coisa pior que um erro aqui é passar em falso e falhar de verdade em algum lugar que importa mais.
O que escrever no lugar de um comentário
Três saídas honestas, dependendo do que o comentário era de fato. Se ele explicava um valor específico, uma chave irmã como "timeout_note" funciona, ao custo de virar um dado que o seu código agora precisa ignorar em vez de metadado que um leitor pode pular. Se o arquivo é genuinamente pensado para ser editado por uma pessoa e relido por um programa que você controla, e comentários são uma das várias coisas que você quer de volta, o movimento maior é parar de brigar com o JSON por causa disso — o trade-off entre YAML e JSON cobre o que mais você ganha e perde ao trocar. E se o destino insiste em JSON rigoroso não importa o quê, escrever o arquivo de origem em JSON5 ou JSONC e reduzi-lo a JSON simples num passo de build te dá comentários durante o desenvolvimento e um arquivo que não vai surpreender nada lá na frente — o que é bem parecido com o que Crockford sugeriu desde o início, só que automatizado.
Um caso se resolve sozinho, sem nada disso: se o arquivo que você está encarando não parseia e você não entende por quê, e descobre que tem comentários dentro, isso não é um problema novo — é o mesmo quase-acerto coberto em como formatar JSON minificado, onde JSON5 e JSONC aparecem como um dos poucos motivos de um arquivo parecer JSON e não ser.
O formatador de JSON daqui não vai ler um arquivo com comentários, e vai te dizer exatamente onde desistiu em vez de chutar — cole um tsconfig.json nele e o primeiro // é onde ele para. Se o que te trouxe até aqui de fato é um arquivo que não parseia por algum outro motivo, como formatar JSON minificado percorre o resto da lista: vírgulas finais, respostas truncadas e os números que perdem precisão caladinhos pelo caminho.
Perguntas frequentes
Dá para colocar comentários em um arquivo JSON?
Não no JSON padrão — não existe sintaxe de comentário, e o JSON.parse e qualquer outro parser rigoroso rejeitam o arquivo assim que encontram um. Você pode escrever comentários em um arquivo JSON5 ou JSONC em vez disso, ou removê-los num passo de build antes de o parser rigoroso vê-los.
Qual é a diferença entre JSON5 e JSONC?
JSON5 é a extensão maior: comentários mais chaves sem aspas, strings entre aspas simples, vírgulas finais e alguns formatos numéricos que o JSON proíbe, pensado para ser um formato que as pessoas escrevem à mão. JSONC só acrescenta comentários e uma vírgula final tolerada, e existe principalmente porque o Visual Studio Code precisava de um lugar para colocar as próprias configurações comentadas.
O tsconfig.json aceita comentários?
Aceita. O compilador do TypeScript lê o tsconfig.json como JSONC, então comentários // e /* */ e uma vírgula final são normais ali, mesmo o arquivo tendo extensão .json. Já o package.json, lido pelo npm, não recebe o mesmo tratamento e falha com o mesmo comentário.
Por que Douglas Crockford tirou os comentários do JSON?
Segundo o próprio relato dele, ele tinha visto gente usar comentários para carregar diretivas de parsing — instruções pensadas para um parser específico em vez de dados — o que quebrava a garantia de que qualquer parser conforme lê um documento JSON do mesmo jeito. Tirar a sintaxe de comentários por completo fechou essa porta em vez de tentar fiscalizar como os comentários eram usados.
Colocar um comentário quebra o package.json?
Quebra, na hora. O npm parseia o package.json como JSON rigoroso, então um // ou um /* */ em qualquer parte do arquivo é um erro de sintaxe, e a instalação ou o script que o lê vai falhar antes de fazer qualquer outra coisa. Não existe um jeito suportado de contornar isso além de remover o comentário.
Última atualização 25 de setembro de 2026
