FormatArc JSON Formatter processando um arquivo JSONC com os comentários JSON removidosFormatArc JSON Formatter processando um arquivo JSONC com os comentários JSON removidos
Publicado: 2026-04-13Atualizado: 2026-07-15

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.

Como corrigir "Comments are not permitted in JSON" no VS Code

Esse aviso vem do serviço de linguagem JSON do VS Code e, na prática, significa "este arquivo está associado ao modo JSON estrito". A correção certa depende de quem vai ler o arquivo:

O arquivo suporta comentários de forma legítima (JSONC)

Clique no indicador de linguagem JSON na barra de status (canto inferior direito), escolha Alterar modo de linguagem e selecione JSON with Comments. Os sublinhados somem na hora: o arquivo passa a ser analisado como JSONC, o mesmo modo que o VS Code já usa para settings.json e tsconfig.json.

A troca vale só para a sessão atual do editor. Para torná-la permanente para um arquivo ou um padrão de nomes, associe-o no seu settings.json:

{
  "files.associations": {
    "*.config.json": "jsonc"
  }
}

Um parser estrito vai ler o arquivo

Alterar o modo de linguagem só silencia o editor. Se o arquivo for consumido depois por JSON.parse, pelo json.loads do Python ou por qualquer outro parser estrito, o erro em tempo de execução continua: os comentários precisam sair. Mova as anotações para um campo _comment ou remova-os antes de publicar.

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.

JSONCJSON5
Especificação oficialNãoSim (spec.json5.org)
ComentáriosSimSim
Vírgulas finaisÀs vezesSim
Chaves sem aspasNãoSim
Strings com aspas simplesNãoSim
EcossistemaMicrosoft / VS CodeIndependente, npm e outros

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.

RecursoPermitido pela RFC 8259?JSONCJSON5
Comentário de linha única //NãoSimSim
Comentário de bloco /* */NãoSimSim
Vírgula finalNãoOpcionalSim
Chaves sem aspasNãoNãoSim
Strings com aspas simplesNãoNãoSim

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.

FormatArc JSON Formatter exibindo um payload JSON limpo e formatadoFormatArc JSON Formatter exibindo um payload JSON limpo e formatado

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:

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

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

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