JSON pode ter comentários
Resumo: A RFC 8259 não tem sintaxe de comentário, então `//` e comentários de bloco fazem `JSON.parse` lançar erro. Use JSON5 ou JSONC, um campo `_comment`, um `description` de Schema ou YAML.
Resumo da ópera: nunca coloque comentários em JSON padrão; use JSONC ou JSON5 para configuração local que só humanos editam, mova as explicações para um description de JSON Schema quando o arquivo cruza sistemas, e mude para YAML ou TOML quando o volume de anotações crescer.
Não.
Qualquer analisador em conformidade com o padrão rejeita isto:
{
"port": 8080 // apenas desenvolvimento local
}
O Chrome informa SyntaxError: Unexpected token }. O analisador encontrou /, que não pode iniciar nenhum valor JSON, e parou.
Por que a especificação exclui comentários de propósito
A RFC 8259 define seis valores: objeto, array, número, string, true/false, null. Não há produção de comentário.
Comentários foram propostos cedo e rejeitados por um motivo concreto: uma vez que comentários são legais, alguém os usa para carregar diretrizes — includes condicionais, variáveis de template — e todo analisador desenvolve seu próprio dialeto. A interoperabilidade quebra no primeiro salto. O JSON é deliberadamente apenas dados, sem nada executável dentro dele.
Quatro formas de manter suas notas
1. Use um superconjunto. JSON5 e JSONC aceitam os dois estilos de comentário. settings.json e tsconfig.json do VS Code são JSONC.
O custo é real: JSON.parse ainda os rejeita, e APIs, pipelines de log e filas de mensagens geralmente aceitam apenas JSON padrão. Seu comentário é descartado silenciosamente ou lança erro em algum ponto a jusante.
2. Coloque a nota nos dados.
{
"_comment": "porta atribuída pela operação, não altere",
"port": 8080
}
Funciona em toda parte, mas polui o modelo: todo consumidor precisa saber quais chaves ignorar, e sua definição de tipo ganha um campo que não é realmente dado.
3. Use um description de Schema. description é destinado a humanos e ferramentas. Validadores o expõem, editores o mostram ao passar o mouse, e ele nunca entra no payload. Esta é a única opção que sobrevive à manutenção de longo prazo sem quebrar compatibilidade.
4. Mude o formato do arquivo. Se o arquivo existe para ser editado à mão, YAML ou TOML suportam comentários nativamente. Brigar com JSON aqui é esforço desperdiçado.
Escolhendo
| Situação | Resposta |
|---|---|
| Enviado a outro sistema, através de uma API ou de uma fila | Sem comentários; documente em Schema ou em docs externos |
| Configuração lida apenas por humanos e editores | JSONC, com extensão .jsonc |
| Precisa de ferramentas universais e explicação inline | JSON padrão mais description de Schema |
| Configuração longa com muitas anotações | Mude para YAML |
Perguntas frequentes
Por que um campo _comment polui o modelo?
Porque ele se torna parte dos dados. Todo consumidor precisa saber quais chaves ignorar, e a definição de tipo ganha um campo que não é realmente dado de negócio.
A explicação deve viver em um description de JSON Schema?
Sim. description fica fora do payload, enquanto validadores o expõem e editores o mostram ao passar o mouse, então é a única opção que sobrevive à manutenção de longo prazo sem quebrar compatibilidade.
JSONC ou JSON5 podem ser analisados por JSON.parse?
Não. JSON.parse ainda rejeita comentários, e APIs, pipelines de log e filas de mensagens geralmente aceitam apenas JSON padrão, então o comentário é descartado ou lança erro em algum ponto a jusante.
Ferramentas
- Analisador JSON5 — cole uma configuração comentada e veja a estrutura resultante
- Formatador e validador JSON — JSON ilegal é informado com linha e coluna, então o comentário problemático fica óbvio