Ferramentas para desenvolvedores · Formatador e validador JSON
Por que JSON não tem comentários: a decisão de design e suas soluções alternativas
· Fundo
JSON padrões validação
Os comentários foram removidos de JSON deliberadamente. Esta postagem explica o motivo, por que cada tentativa de adicioná-los de volta criava um novo formato e quais são suas opções quando um arquivo de configuração realmente precisa de uma anotação.
O comentário que quebrou a construção
O comentário que quebrou a compilação — uma nota útil adicionada a uma configuração JSON e um analisador que parou na primeira barra. O autor pode ter copiado um padrão de JavaScript ou de um editor compatível com JSONC, enquanto a ferramenta de implantação usa JSON estrito. O realce de sintaxe pode fazer com que a nota pareça legítima, mesmo que o consumidor rejeite o primeiro marcador de comentário.
Os comentários são rejeitados porque a barra não é um token JSON onde o scanner espera um valor ou membro. ToolAcre não remove silenciosamente a sintaxe JSONC ou JSON5. Uma propriedade convencional em forma de comentário são dados comuns e podem violar o esquema de um aplicativo, mesmo que a sintaxe estrita JSON a aceite. Afirmações históricas não comprovadas sobre o design de JSON são omitidas ou corrigidas, em vez de apresentadas como fatos estabelecidos, sem evidências primárias ou uma fonte de padrões rastreáveis disponíveis para verificação.
A razão de Crockford para remover comentários
A razão de Crockford para remover comentários - uma explicação posterior diz que os comentários foram usados para transportar diretivas de análise, minando a interoperabilidade entre implementações. A consequência relevante do design é que o padrão JSON não possui token de comentário. Afirmações sobre motivações privadas, cronologia exata ou resposta universal da indústria requerem fontes históricas não fornecidas por este repositório.
Conseqüentemente, afirmações históricas não comprovadas são omitidas ou corrigidas aqui. O padrão observável e o comportamento do analisador são suficientes: JSON estrito troca dados por meio de seis tipos de valor e dois contêineres, sem um canal de anotação. Essa restrição impede que um destinatário atribua significado operacional ao texto que outro destinatário ignora, mas também torna JSON menos confortável para configuração mantida manualmente.
O que um validador relata em um comentário
O que um validador relata em um comentário — `//` e `/* */` não está na gramática, então o erro cai na primeira barra com linha e coluna. O scanner não está contestando as palavras da nota. Ele não pode iniciar nenhum valor JSON, nome de membro ou separador válido com `/` nessa posição.
Para `{"port":8080, // local only "secure":false}`, a vírgula é válida e o próximo token legal deve ser um nome de propriedade entre aspas ou a chave de fechamento. A barra viola essa expectativa. A remoção apenas da nota deixa um separador válido e o próximo membro; excluir a pontuação próxima pode criar um segundo erro. Revalide a saída estrita exata após cada edição.
Os formatos que adicionaram comentários de volta
Os formatos que adicionaram comentários de volta - JSONC permitem comentários em torno da sintaxe JSON que de outra forma seria familiar, enquanto JSON5 adiciona conveniências como chaves de identificador sem aspas e vírgulas finais. Hjson enfatiza a edição humana com sintaxe adicional relaxada. YAML tem sua própria gramática, incluindo comentários, e não é apenas JSON com anotações adicionadas.
A aceitação é específica do consumidor: as configurações do editor e a configuração do TypeScript podem usar analisadores tolerantes a comentários, enquanto um manifesto de pacote ou corpo API pode exigir JSON estrito. Kubernetes normalmente consome YAML ou JSON de acordo com suas ferramentas. Nomeie o formato real na documentação e no manuseio de arquivos; remover extensões ou chamar cada notação de objeto “JSON” oculta os limites de compatibilidade.
Soluções alternativas dentro de JSON estrito
Soluções alternativas dentro de JSON estrito — uma chave `_comment` ou `//` convencional armazena explicação como um membro de string comum. Ele sobrevive à análise rigorosa porque tanto a chave quanto o valor usam tokens padrão. Múltiplas notas precisam de chaves exclusivas ou de um array, pois nomes de membros duplicados não são confiáveis e podem ser recolhidos por analisadores.
A solução alternativa altera o modelo de dados. Um esquema com `additionalProperties: false` pode rejeitar a anotação e um aplicativo pode persistir ou transmiti-la como configuração real. Documentação externa, um vizinho README ou um esquema `description` geralmente fornece um canal de explicação mais seguro. Use membros em forma de comentário somente quando cada consumidor permitir e ignorá-los explicitamente.
Exemplo resolvido: um arquivo de configurações anotado
Exemplo resolvido: um arquivo de configurações anotado - comece com uma fonte JSONC contendo `// seconds before retry` acima de `"timeout":30`. Se o destino aceitar apenas JSON, use um analisador que entenda JSONC para produzir dados e, em seguida, serialize esses dados como JSON estrito. O artefato implantado torna-se `{"timeout":30}` enquanto a fonte mantida mantém sua explicação.
Não remova comentários com expressões regulares. Sequências de barras podem aparecer legitimamente dentro de strings, como URLs, e padrões de comentários em bloco podem abranger linhas de maneiras que a substituição textual é mal tratada. Mantenha a origem e o artefato gerado distintos, valide o resultado estrito e organize a regeneração na construção. Isso preserva as notas do autor sem fingir que o analisador receptor as apoia.
O que isso não cobre
O que isso não cobre — como configurar analisadores individuais para aceitar comentários, o que é específico da ferramenta e muda frequentemente. Uma opção permissiva em uma biblioteca não altera a gramática JSON nem garante que outro serviço aceitará o mesmo texto. Verifique o analisador, a versão e o destino em vez de depender da exibição de um editor.
Este artigo também evita afirmações não comprovadas sobre exatamente quando os comentários foram removidos, quem adotou cada solução alternativa primeiro ou se uma decisão de design por si só causou a popularidade de JSON. Tais afirmações históricas necessitam de fontes primárias independentes. Aqui eles são omitidos ou corrigidos; a conclusão suportada é limitada à sintaxe estrita atual, ao comportamento do repositório e às diferenças operacionais entre os formatos nomeados.
Conclusão: JSON é um formato de intercâmbio de dados, não uma linguagem de configuração
Conclusão: JSON é um formato de intercâmbio de dados, não uma linguagem de configuração rica em comentários — e o validador mostra exatamente onde uma nota quebra a gramática estrita. Quando humanos precisarem de anotações, escolha um formato que a ferramenta de consumo suporte oficialmente ou mantenha uma fonte anotada que gere um artefato estrito separado. Não presuma que os comentários serão ignorados inofensivamente.
Se JSON estrito for obrigatório, mova a explicação para a documentação ou use metadados aprovados pelo esquema e valide o documento final. ToolAcre relata intencionalmente a primeira barra em vez de excluir material silenciosamente, porque a conversão silenciosa pode alterar strings ou ocultar uma incompatibilidade de formato. O contexto histórico deve permanecer igualmente disciplinado: afirmações não suportadas são omitidas ou corrigidas, enquanto a sintaxe observável e o comportamento do analisador levam a conclusão.