JSON con Commenti

JSONC (JSON with Comments) estende il JSON standard per consentire commenti in stile JavaScript. Molti strumenti di sviluppo usano JSONC per i file di configurazione dove i commenti aiutano a documentare le impostazioni. Questo parser rimuove i commenti per produrre JSON valido preservando la struttura dei dati.

Specifiche

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Casi d'uso comuni

• Analisi di tsconfig.json e jsconfig.json per progetti TypeScript/JavaScript
• Lettura di settings.json di VS Code e configurazioni delle estensioni
• Elaborazione dei file di configurazione wrangler.jsonc di Cloudflare
• Modifica delle configurazioni di ESLint, Prettier e altri strumenti con documentazione inline

Funzionalità

• Analisi dei commenti a riga singola (// commento)
• Analisi dei commenti multiriga (/* commento */)
• Gestione delle virgole finali (comuni nei file JSONC)
• Rimozione dei commenti per produrre output JSON valido
• Tutte le funzionalita del Parser JSON standard (vista ad albero, conversione)

Esempi

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Suggerimenti

• VS Code, TypeScript e molti strumenti moderni supportano JSONC nativamente.
• Quando condividi configurazioni, considera se gli strumenti dei destinatari supportano i commenti.
• Converti in JSON standard rimuovendo i commenti quando gli strumenti richiedono JSON rigoroso.

Approfondimenti JSON con Commenti

JSONC (JSON with Comments) e un'estensione del JSON standard che consente commenti in stile JavaScript a riga singola (//) e multiriga (/* */), nonche virgole finali dopo l'ultimo elemento in array e oggetti. Sebbene non sia uno standard ufficiale, JSONC e diventato il formato de facto per i file di configurazione rivolti agli sviluppatori dove la documentazione inline migliora la manutenibilita.

Microsoft ha reso popolare JSONC attraverso Visual Studio Code, che lo usa per settings.json, keybindings.json, launch.json e extensions.json. Il tsconfig.json di TypeScript e il jsconfig.json di JavaScript sono file JSONC, cosi come molte configurazioni di ESLint, Prettier e Babel quando usano l'estensione .json. Il wrangler.jsonc di Cloudflare usa esplicitamente l'estensione .jsonc per segnalare il supporto ai commenti.

Il vantaggio chiave di JSONC rispetto al JSON semplice e la documentazione. I file di configurazione contengono spesso impostazioni il cui scopo non e ovvio dal solo nome della chiave. I commenti consentono agli sviluppatori di spiegare perche esiste un'impostazione, quali sono i valori validi e quali sono le conseguenze delle modifiche. Le virgole finali riducono il rumore nel controllo versione consentendo all'ultimo elemento di avere lo stesso formato di tutti gli altri, cosi l'aggiunta di un nuovo elemento mostra solo una riga modificata in un diff invece di due.

Dietro le quinte, i parser JSONC funzionano rimuovendo i commenti e le virgole finali prima di passare il risultato a un parser JSON standard. Questo significa che il modello dati e identico a JSON: i commenti sono metadati per gli umani, non dati per i programmi. Quando si converte JSONC in JSON per strumenti che richiedono la conformita JSON rigorosa, i commenti vengono semplicemente rimossi. La libreria node-jsonc-parser di Microsoft, usata in VS Code, e l'implementazione di riferimento per l'analisi JSONC.

JSONC non e uno standard ufficiale definito da alcun RFC o specifica ECMA. E una convenzione resa popolare da Microsoft attraverso VS Code e TypeScript, con un comportamento ben definito dalla libreria jsonc-parser che funge da implementazione di riferimento. Altri strumenti che supportano JSONC, come ESLint, Prettier e vari editor, seguono le stesse convenzioni per commenti a riga singola, commenti multiriga e virgole finali. I file JSONC comuni includono tsconfig.json e jsconfig.json (TypeScript/JavaScript), i file di impostazioni di VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) e varie altre configurazioni di strumenti. Qualsiasi file JSON modificato principalmente dagli sviluppatori che potrebbe beneficiare di commenti probabilmente supporta JSONC.

JSONC dovrebbe essere usato solo per file di configurazione letti da strumenti con supporto esplicito JSONC. Le risposte API, l'archiviazione dati e la comunicazione tra servizi dovrebbero sempre usare JSON standard, poiche la maggior parte dei parser JSON rifiutera i commenti come errori di sintassi. Per elaborare un file di configurazione JSONC programmaticamente con un parser JSON standard, rimuovi prima i commenti usando una libreria compatibile con JSONC.

JSONC e piu conservativo di JSON5, che e un superset piu esteso di JSON. Mentre JSONC aggiunge solo commenti e virgole finali, JSON5 consente anche stringhe tra singoli apici, chiavi oggetto senza virgolette, numeri esadecimali, punti decimali iniziali e finali, Infinity e NaN, e stringhe multiriga. JSONC ha un supporto piu ampio negli strumenti dell'ecosistema degli sviluppatori, mentre JSON5 e usato in file di configurazione specifici come il babel.config.json5 di Babel ma ha un'adozione piu ristretta nel complesso.