JSON permite comentários? A RFC 8259 diz que não, mas aqui vão 4 soluções

JSON suporta comentários? — a resposta curta

Não. A RFC 8259 não permite comentários // ou /* ... */ em nenhum lugar de um documento JSON. A proibição é estrutural: a gramática da Seção 2 os exclui, então um parser estrito precisa rejeitar qualquer comentário com um erro "Unexpected token". A Seção 9, porém, afirma que um parser "PODE aceitar formas não-JSON ou extensões" — é essa única frase que permite a existência de JSONC e JSON5 como alternativas legítimas.

Se você precisa de comentários no seu JSON, tem quatro opções práticas:

• JSONC — JSON with Comments, usado pelo VS Code
• JSON5 — um superconjunto bem especificado de JSON que também adiciona comentários, vírgulas finais e mais
• Um campo de contorno como "_comment": "..." que vive dentro do próprio JSON
• Remover os comentários antes de passar o arquivo para um parser estrito

Este artigo percorre cada opção, explica quando escolher cada uma e mostra como converter um arquivo JSON com comentários em um JSON limpo que você pode usar em qualquer lugar.

Decisão rápida:

• Se você está editando um arquivo de configuração do VS Code ou da Microsoft: use JSONC
• Se você está escolhendo um formato de configuração para um projeto novo: use JSON5
• Se o parser é estrito e você não pode trocá-lo: use um campo _comment ou remova os comentários

Depois de remover os comentários, você pode formatar e verificar o resultado no JSON Formatter da FormatArc — tudo roda no navegador e nada sai da sua máquina. Para dicas sobre como produzir uma saída JSON limpa e fácil de revisar, veja Dicas de Formatação de JSON.

O que a RFC 8259 realmente diz sobre comentários

A RFC 8259 (Internet Standard 90, dezembro de 2017) não contém a palavra "comment" em nenhum lugar. Os comentários são excluídos estruturalmente, não por uma proibição explícita.

A gramática (Seção 2)

A gramática inteira do JSON cabe em poucas linhas de ABNF. Os únicos caracteres insignificantes entre tokens são quatro bytes de espaço em branco:

ws = *(
        %x20 /              ; Space
        %x09 /              ; Horizontal tab
        %x0A /              ; Line feed
        %x0D )              ; Carriage return

// e /* */ não estão na gramática, então um parser estrito precisa rejeitá-los com um erro "Unexpected token". Essa é a razão formal pela qual todo parser JSON conforme ao padrão se recusa a aceitar comentários — simplesmente não existe nenhuma regra de produção que os aceite.

O que os parsers PODEM fazer (Seção 9)

A mesma RFC permite extensões de forma explícita:

A JSON parser MUST accept all texts that conform to the JSON grammar. A JSON parser MAY accept non-JSON forms or extensions.

É essa única frase que permite a existência de JSONC e JSON5 sem violar o padrão. Eles são "extensões" que a RFC permite explicitamente, desde que os dados enviados pela rede ainda estejam em conformidade com a gramática estrita, para que qualquer outro parser consiga lê-los.

A mesma regra em todas as revisões da especificação

A especificação IETF do JSON passou por três revisões — RFC 4627 (2006), RFC 7159 (2014) e RFC 8259 (2017) — e nenhuma delas jamais incluiu comentários na gramática. A ECMA-404, o padrão ECMA paralelo, adota a mesma posição. Comentários estão fora do JSON desde a primeira vez que o formato foi escrito.

Por que a especificação do JSON não permite comentários

Douglas Crockford, o criador original do JSON, removeu os comentários de propósito. Nas próprias palavras dele, as pessoas estavam usando comentários para embutir diretivas de parsing, o que quebrava a interoperabilidade. A especificação foi simplificada para que quaisquer dois parsers JSON se comportassem de forma idêntica.

O resultado é que o JSON é:

• Pequeno — a gramática cabe em uma página
• Não ambíguo — cada valor tem exatamente uma interpretação
• Portável — toda linguagem tem um parser embutido que se comporta da mesma forma

O custo é óbvio: você não pode anotar um arquivo JSON para explicar por que uma configuração existe. Esse é o trade-off, e também é a razão pela qual tantas ferramentas recorrem a um superconjunto como JSONC ou JSON5.

Para as regras de sintaxe subjacentes, veja o Guia de Sintaxe do JSON.

Opção 1: JSONC — JSON with Comments

JSONC é uma extensão informal inventada na Microsoft e usada por todo o VS Code. Ele adiciona duas coisas em cima do JSON:

• // comentários de linha única
• /* comentários de múltiplas linhas */

Todo o resto é igual ao JSON. Um arquivo JSONC normalmente se parece com isto:

{
  // Which theme VS Code should use at startup
  "workbench.colorTheme": "Default Dark Modern",

  /* Editor settings
     applied to every language */
  "editor.tabSize": 2,
  "editor.formatOnSave": true
}

O settings.json, tsconfig.json, launch.json do VS Code e muitas ferramentas da Microsoft esperam JSONC. Você também vai encontrá-lo em configurações do Deno (deno.json) e em outras ferramentas de desenvolvimento.

Como fazer parsing de JSONC

JSONC não é suportado pelo JSON.parse embutido — você precisa de um auxiliar.

Node.js:

// npm install jsonc-parser
import { parse } from "jsonc-parser";
const data = parse(sourceText);

Python:

# pip install jstyleson
import jstyleson
data = jstyleson.loads(source_text)

O próprio VS Code vem com seu próprio parser JSONC — é por isso que você consegue escrever comentários dentro do settings.json sem quebrar nada.

Opção 2: JSON5 — uma especificação mais limpa

JSON5 (json5.org) é um superconjunto formalmente especificado do JSON que adiciona várias comodidades do ECMAScript 5:

• Comentários de linha única e de múltiplas linhas
• Vírgulas finais em objetos e arrays
• Chaves sem aspas (quando são identificadores válidos)
• Aspas simples para strings
• Strings de múltiplas linhas com continuação de linha
• Números hexadecimais, pontos decimais no início e no fim, e Infinity e NaN explícitos

Um arquivo JSON5 pode ter uma aparência notavelmente relaxada:

{
  // Feature flags for the staging environment
  features: {
    newDashboard: true,
    legacyNotifications: false,
    rateLimitRps: 0xff,
  },
  welcomeMessage: 'Hello, world',
  /* trailing commas are fine */
}

Como o JSON5 tem uma especificação de verdade, existem bibliotecas para ele em quase toda linguagem: json5 para Node.js, pyjson5 para Python, json5 para Ruby, e assim por diante.

JSONC vs JSON5: qual você deve usar?

Eles se parecem, mas têm trade-offs diferentes.

Uma regra prática simples:

• Se você está editando um arquivo de configuração da Microsoft ou do VS Code, você já está usando JSONC — continue fazendo isso
• Se você está escolhendo um formato de configuração para um projeto novo e quer uma especificação para apontar suas ferramentas, escolha JSON5
• Se a interoperabilidade com parsers JSON estritos for crítica, fique no JSON puro e use o padrão de campo de contorno abaixo

Suporte de implementação: o que cada forma realmente permite

A tabela abaixo compara cinco recursos "não-JSON" comuns com o padrão estrito e os dois superconjuntos. A coluna RFC 8259 reflete a gramática da RFC 8259 Seção 2 (a mesma gramática codificada na ECMA-404); a coluna JSON5 reflete a especificação JSON5 publicada; a coluna JSONC reflete a extensão informal da Microsoft conforme documentada para o VS Code.

A coluna RFC 8259 é "Não" em todas as linhas porque a gramática da Seção 2 não tem nenhuma regra de produção para nenhum desses recursos — strings precisam de aspas duplas, chaves são strings e não há nenhum elemento após o último valor de um objeto ou array. O JSON5 permite os cinco porque sua especificação adiciona explicitamente a sintaxe do ECMAScript 5. O JSONC sempre adiciona as duas formas de comentário e mantém as chaves e strings com aspas duplas do JSON estrito; o suporte a vírgulas finais depende do parser (a especificação do JSONC diz que os parsers PODEM aceitá-las, e o jsonc-parser de referência deixa allowTrailingComma desativado por padrão), e é por isso que a célula diz "Opcional" em vez de um "Sim" categórico.

Soluções de contorno para JSON estrito

Se você não pode trocar o parser — por exemplo, porque um serviço de terceiros espera JSON puro — ainda dá para deixar anotações dentro do arquivo usando campos de string comuns.

Padrão 1: o campo _comment

{
  "_comment": "Increase retries before the upstream timeout kicks in",
  "retries": 3,
  "timeout_ms": 5000
}

Chaves prefixadas com sublinhado são convencionalmente ignoradas pelos consumidores, e a maior parte do código as trata como dados comuns. Essa é a solução de contorno mais simples.

Padrão 2: chaves irmãs para comentários por campo

{
  "retries": 3,
  "retries_comment": "Any higher and we exceed the upstream timeout",
  "timeout_ms": 5000,
  "timeout_ms_comment": "Matches the load balancer timeout"
}

Mais verboso, mas deixa claro qual comentário pertence a qual campo.

Padrão 3: bloco externo de metadados

{
  "$meta": {
    "generated_by": "deploy.sh",
    "purpose": "Service configuration for the staging environment"
  },
  "service": {
    "port": 8080,
    "retries": 3
  }
}

Um objeto de metadados de nível superior mantém o payload limpo enquanto preserva o contexto.

Essas soluções de contorno adicionam dados reais ao arquivo, o que significa que parsers estritos ainda os aceitam. A desvantagem é que os campos extras passam a fazer parte do schema e precisam ser documentados como tais.

Remova os comentários antes de usar um parser estrito

Se você tem um arquivo JSONC ou JSON5 e precisa passá-lo para um parser JSON estrito, tem duas opções: fazer o parsing com uma biblioteca JSONC/JSON5 e re-serializar como JSON, ou remover os comentários com uma regex.

Exemplo rápido em Node.js usando o pacote json5:

// npm install json5
import JSON5 from "json5";
import fs from "node:fs";

const source = fs.readFileSync("config.json5", "utf8");
const data = JSON5.parse(source);
fs.writeFileSync("config.json", JSON.stringify(data, null, 2));

Ou uma abordagem minimalista com regex — boa para arquivos que você controla, mas frágil se as strings puderem conter //:

const stripped = source
  .replace(/\/\/[^\n\r]*/g, "")
  .replace(/\/\*[\s\S]*?\*\//g, "");
const data = JSON.parse(stripped);

O caminho mais seguro é sempre usar um parser de verdade. Depois que os comentários sumirem, veja as Dicas de Formatação de JSON para lidar com estruturas complexas e detectar qualquer erro de sintaxe remanescente.

Formate o resultado com a FormatArc

Quando você já tem JSON puro, cole-o no JSON Formatter da FormatArc para formatar a saída e identificar qualquer problema remanescente. Se o parser ainda estiver reclamando — normalmente com um erro "Unexpected token /" — esse erro quase sempre significa que ainda há um comentário no arquivo. Veja Como Corrigir Erros de Parse de JSON para a lista completa de causas.

A própria FormatArc usa o JSON.parse embutido, então ela rejeita JSONC e JSON5 diretamente. O fluxo de trabalho é:

1. Remova os comentários (ou faça o parsing com uma biblioteca JSONC/JSON5 e depois serialize)
2. Cole o resultado no JSON Formatter
3. Leia, verifique ou copie o JSON limpo

Tudo roda no navegador — nada sai da sua máquina.

Perguntas frequentes

Comentários JSON são permitidos na RFC 8259?

Não. Comentários JSON não são permitidos pela RFC 8259. A gramática da especificação na Seção 2 não tem nenhuma regra de produção para // ou /* */, então qualquer parser conforme precisa rejeitá-los como "Unexpected token". As alternativas compatíveis com o padrão são JSONC, JSON5 ou remover os comentários antes do parsing.

A RFC 8259 diz explicitamente que comentários JSON não são permitidos?

Não com essas palavras — a RFC 8259 nunca usa o termo "comment". A proibição é implícita. A Seção 2 define toda a gramática do JSON em ABNF e lista apenas quatro caracteres insignificantes entre tokens (espaço, tab, line feed, carriage return). Como // e /* */ estão ausentes da gramática, um parser conforme precisa rejeitá-los. A Seção 9, então, permite que os parsers aceitem "formas não-JSON ou extensões", o que é a base legal para JSONC e JSON5.

Onde a RFC 8259 diz que comentários JSON não são permitidos?

A RFC 8259 nunca usa a palavra "comment". A proibição é estrutural: a Seção 2 define toda a gramática do JSON em ABNF, e os únicos caracteres insignificantes entre tokens são espaço, tab, line feed e carriage return (ws = *( %x20 / %x09 / %x0A / %x0D )). Não existe nenhuma regra de produção para // ou /* */, então um parser conforme precisa rejeitá-los como "Unexpected token". A Seção 9, então, permite que os parsers aceitem "formas não-JSON ou extensões" — o que é a base legal para JSONC e JSON5.

Por que o settings.json e o tsconfig.json do VS Code permitem comentários?

Ambos os arquivos são tecnicamente JSON inválido sob a RFC 8259, mas o VS Code e o compilador do TypeScript trazem seus próprios parsers JSONC e tratam os arquivos como JSONC em vez de JSON estrito. Esse é exatamente o caso de "formas não-JSON ou extensões" que a Seção 9 permite. O trade-off é a portabilidade: outras ferramentas que usam JSON.parse diretamente vão falhar no mesmo arquivo com um erro "Unexpected token /", a menos que também entendam JSONC.

Posso usar comentários // ou /* em um arquivo .json comum?

Não se o arquivo for lido por um parser estrito como JSON.parse, json.loads ou encoding/json. O parser vai rejeitar o arquivo com um erro "Unexpected token" no primeiro comentário. Renomeie o arquivo para .jsonc e use um loader que entenda JSONC, ou mude para JSON5.

Por que o VS Code me deixa escrever comentários no settings.json?

O VS Code trata o settings.json e arquivos semelhantes como JSONC, não como JSON estrito. Seu parser embutido aceita comentários // e /* */. Outros editores que usam JSON.parse para ler o mesmo arquivo vão falhar, a menos que também entendam JSONC.

JSON5 é um padrão?

JSON5 tem uma especificação publicada em spec.json5.org, mas não é um padrão da IETF nem da ECMA. Ele é amplamente suportado em ferramentas de desenvolvimento, mas não é um substituto para o JSON da RFC 8259 em APIs ou em dados que trafegam pela rede.

Devo usar _comment ou mudar para JSON5 no meu arquivo de configuração?

Se o arquivo é lido por muitas ferramentas diferentes — algumas das quais só entendem JSON estrito — fique no JSON puro e use o padrão _comment. Se o arquivo é consumido apenas por código que você controla, o JSON5 te dá comentários de verdade e é menos ruidoso.

A FormatArc suporta JSONC ou JSON5?

As ferramentas da FormatArc usam o JSON.parse embutido do navegador, que é estrito. Você vai precisar remover os comentários ou fazer o parsing por uma biblioteca JSONC/JSON5 primeiro e depois colar o resultado no JSON Formatter da FormatArc.

E quanto ao YAML?

YAML suporta comentários nativamente com #. Se o que você mais precisa são os comentários e você pode mudar de formato, o YAML costuma ser a melhor escolha para arquivos de configuração. Veja YAML vs JSON: Principais Diferenças para a comparação completa, ou vá direto para o Guia de Sintaxe do YAML.

Leitura relacionada

Se você quer entender melhor o próprio JSON:

• O que é JSON? — o básico do formato
• Guia de Sintaxe do JSON — as regras que o JSON estrito segue

Se você escolheu JSONC ou JSON5 e precisa trabalhar com a saída:

• Dicas de Formatação de JSON — saída limpa depois que os comentários sumirem
• Como Corrigir Erros de Parse de JSON — quando os comentários passam despercebidos

Se você precisa de comentários e pode trocar de formato:

• YAML vs JSON: Principais Diferenças — a alternativa amigável a configurações
• Guia de Sintaxe do YAML — aprenda YAML se você precisa de comentários e mais

Resumo

• JSON padrão não suporta comentários — isso é intencional
• JSONC adiciona comentários // e /* */ e é usado pelo VS Code
• JSON5 é um superconjunto formal com comentários, vírgulas finais e sintaxe mais flexível
• Se você não pode trocar o parser, adicione um campo _comment ou um bloco externo de metadados
• Depois de remover os comentários, formate o resultado no JSON Formatter da FormatArc