O que é JSONC e é melhor que JSON?

JSON se tornou um formato de dados quase onipresente, usado em respostas de API, salvamento de arquivos de jogos e configuração. Mas muitas pessoas sentem que pode ser melhor, e várias tentativas foram feitas para expandi-lo ou melhorá-lo. JSONC é uma dessas tentativas.

O que é JSONC e por que foi criado?

JavaScript Object Notation (JSON) é um formato de texto legível para o armazenamento de dados estruturados, usando pares nome-valor, matrizes e valores escalares. Foi fortemente influenciado pela sintaxe JavaScript – daí o nome – mas agora é usado por quase todas as linguagens de programação, em muitos tipos diferentes de ambientes, como um formato neutro para intercâmbio de dados.

Apesar de sua popularidade, o JSON tem seus críticos. As reclamações mais comuns são sobre sua sintaxe e geralmente são uma das seguintes:

• Não permite comentários.
• Não permite vírgulas finais (uma vírgula após o último item de uma matriz ou a última propriedade de um objeto).
• Requer que as chaves (nomes de propriedades) sejam colocadas entre aspas duplas.
• Não tem suporte para strings multilinhas.

Em outras palavras, este é um JSON inválido:

         {
// One of "dark", "light", or "auto"
theme: "light",

description: "This is a description
wrapped over multiple lines for ease
of reading",

// I like LOADS of spaces!
tab-width: 8,
}     

Em vez disso, esses dados precisam ser escritos assim:

         {
"theme": "light",

"description": "This is a description wrapped over multiple lines for ease of reading",

"tab-width": 8
}     

JSONC é uma tentativa, entre muitas, de melhorar o JSON. Outros formatos que tentam fazer algo semelhante incluem YAML e JSON5. Cada um deles é um superconjunto de JSON, portanto, JSON válido também é JSONC, YAML e JSON5 válidos. Os formatos diferem no quanto tentam expandir a sintaxe do JSON.

O YAML faz mudanças significativas e encontrou um nicho na configuração e, ocasionalmente, na documentação. O formato é um pouco híbrido entre Markdown e JSON, com recuo para aninhamento, tipos de dados personalizados e strings multilinhas. YAML é usado por projetos incluindo Docker Compose, fluxos de trabalho em GitHub Actions e a estrutura Ruby on Rails.

Enquanto isso, JSON5 é JavaScript válido, como JSON, por isso se adere mais rigidamente a essa sintaxe. JSON5 visa corrigir todas as reclamações acima sobre JSON e muito mais, mas permanece muito semelhante ao JSON. JSON5 é usado na programação Chromium, Next.js e macOS.

JSONC, por outro lado, é “JSON com comentários”, portanto se concentra inteiramente em permitir comentários dentro de dados JSON. Isto significa que suporta um híbrido dos dois exemplos anteriores:

             { // One of "dark", "light", or "auto" "theme": "light",  /*    I like LOADS    of spaces!    */ "tab-width": 8 }     

JSONC oferece suporte a duas formas comuns de comentários:

• Os comentários embutidos começam com // e duram apenas até o final da linha.
• Os comentários do bloco começam com /* e terminam com */ e podem conter qualquer número de linhas.

A terceira forma comum de comentário — igual ao inline, mas começando com um único caractere “#” — não é suportada.

Quais são as vantagens e desvantagens do JSONC?

JSONC é muito menos popular que JSON, o que por si só é uma desvantagem. Então, o que o JSONC traz para a mesa e é suficiente para que o formato alternativo tenha sucesso?

Os comentários costumam ser valiosos

Primeiro, pessoalmente acho que os comentários são uma vitória maior do que corrigir qualquer outra reclamação comum de JSON. Mudanças na sintaxe para lidar com aspas e vírgulas podem tornar as coisas mais convenientes, mas não oferecem nenhum benefício tão fundamental. Os comentários em arquivos JSON têm dois usos significativos:

• Arquivos de configuração: os comentários podem funcionar como exemplos ou texto de ajuda em modelos de configuração e também podem ser usados ​​para explicar por que uma configuração específica foi escolhida.
• Anotação de dados: os desenvolvedores podem incluir comentários junto com os dados para explicar sua finalidade ou como eles interoperam com outros dados.

Os comentários fornecem um meio de documentação independente; sem eles, os arquivos JSON devem ser explicados em outro lugar, em um local que pode não ser óbvio ou facilmente disponível. Outra solução possível é adicionar dados “fictícios”, por exemplo:

             {    "theme-comment": "The theme value should be one of 'dark', 'light', or 'auto'",    "theme": "dark" }     

Embora isso possa funcionar, é frágil porque depende de qualquer sistema que leia esses dados para ignorar chaves que não reconhece.

Tenha em mente, porém, que os comentários não são universalmente benéficos. Douglas Crockford, o especificador original do JSON, é provavelmente a melhor pessoa para apresentar este argumento:

Removi comentários do JSON porque vi que as pessoas os usavam para manter diretivas de análise, uma prática que teria destruído a interoperabilidade.

Em outras palavras, os comentários estão sujeitos a abusos, o que proibi-los evita.

Ele não lida com vírgulas finais ou chaves sem aspas

Como expliquei acima, considero isso menos importante, mas ainda é uma pequena desvantagem. Se tentarmos consertar o JSON com uma atualização incompatível com versões anteriores, podemos muito bem consertar tudo o que pudermos.

As vírgulas finais são mais fáceis de manter, resultando em menos bugs e patches mais limpos. JSON não permite isso por razões históricas relacionadas à sintaxe confusa do JavaScript. Mas podemos resolver isso agora, e provavelmente deveríamos, mesmo que os benefícios sejam mínimos.

JSONC não é compatível com JSON

Embora JSONC seja um superconjunto de JSON, todo JSON válido também é JSONC válido, o que não funciona ao contrário. A maioria das ferramentas que exigem JSON falharão se você tentar usá-las com um arquivo JSONC:

Isso pode não ser um problema para seu próprio uso, mas torna a adoção generalizada do JSONC muito mais difícil.

É estranho pré-processar

A interoperabilidade será um problema menor se o JSONC puder ser facilmente convertido em JSON. Você pode usar a ferramenta JSMin de Douglas Crockford para fazer exatamente isso. Mas a sintaxe de comentário escolhida pelo JSONC significa que ele deve ser um analisador JSON completo para garantir que os comentários sejam reconhecidos corretamente no contexto.

Se, em vez disso, os comentários fossem indicados com um único caractere “#” na coluna 0, um conversor seria trivial:

         '^#' >output.json
     

Isso significaria que qualquer analisador JSON poderia ser facilmente atualizado para suportar JSONC, em vez de ter que fazer alterações de código mais significativas ou depender de um programa de terceiros como o JSMin.

Como posso usar JSONC hoje?

Na maioria das vezes, você encontrará JSONC quando precisar alterar alguma configuração. Por exemplo, o programa fastfetch lê um arquivo de configuração no formato JSONC, para que você possa anotá-lo com notas, sugestões ou qualquer outra coisa que queira adicionar.

Se você estiver trabalhando com seu próprio código e quiser escrever algo que lide com JSONC e também com JSON, você tem duas opções principais. Primeiro, você pode usar uma ferramenta como JSMin e lidar com JSONC exatamente da mesma maneira que já lida com JSON.

Alternativamente, você pode usar uma biblioteca que lide com JSONC, removendo a dependência de um programa separado. O código fastfetch usa yyjson, uma biblioteca C que lida com comentários JSONC, bem como vírgulas finais e muito mais. O node-jsonc-parser da Microsoft faz algo semelhante para JavaScript e também oferece suporte a vírgulas finais.