Da JSON5 a JSONC: sbloccare un’esperienza di formattazione JSON più permissiva
Quando il JSON stretto ti fa fare debug fino a notte fonda per una virgola mancante, potrebbe essere il momento di incontrare i suoi cugini più permissivi — JSON5 e JSON with Comments (JSONC).
Cos’è JSON5?
JSON5 è un’estensione di JSON che incorpora funzionalità da ECMAScript 5.1, incluse chiavi senza virgolette, virgole finali, stringhe tra apici singoli, commenti e numeri esadecimali. È mantenuto dalla community e progettato per rendere i file di configurazione scritti a mano più leggibili e permissivi del JSON stretto.
Cos’è JSONC?
JSONC (JSON with Comments) è un’estensione minimale del JSON standard che aggiunge supporto per commenti su una riga (//) e su più righe (/* */), oltre alle virgole finali. Mantenuto da Microsoft, è il formato nativo per le impostazioni di VS Code, tsconfig.json e altri file di configurazione TypeScript.
Perché abbiamo bisogno di JSON “permissivo”
- Colli di bottiglia di leggibilità: Il JSON standard vieta commenti, virgole finali, apici singoli, ecc., il che danneggia la chiarezza in config e demo.
- Dolori della collaborazione di team: File JSON enormi senza note inline sono difficili da mantenere; una piccola modifica può rompere l’intero file.
- Realtà DevOps: Kubernetes e le pipeline CI/CD spesso uniscono o generano JSON al volo; una sintassi permissiva taglia le correzioni manuali.
JSON5 vs. JSONC a colpo d’occhio
| Funzionalità | JSON (stretto) | JSON5 | JSONC |
|---|---|---|---|
Commenti // su una riga | No | Sì | Sì |
Commenti /* */ su più righe | No | Sì | Sì |
| Virgole finali | No | Sì | Sì |
| Stringhe tra apici singoli | No | Sì | No |
| Chiavi senza virgolette | No | Sì | No |
Segni numerici + / - | No | Sì | No |
| Numeri esadecimali / binari | No | Sì | No |
| Manutentori della spec | ECMA | Community (A. Rauschmayer) | Microsoft / VS Code |
In una frase: JSON5 sembra un letterale di oggetto JavaScript, mentre JSONC è solo JSON standard più commenti.
Esempi di sintassi
JSON vanilla (stretto)
{
"name": "Go Tools",
"features": ["Base64", "JSON Formatter"]
}Esempio JSON5
// Configurazione progetto
{
name: 'Go Tools', // apici singoli e chiavi senza virgolette
features: [
'Base64',
'JSON Formatter', // virgola finale
],
version: 1.0, // numero non-stringa permesso
}Esempio JSONC
{
// Nome progetto
"name": "Go Tools",
// Lista funzionalità
"features": [
"Base64",
"JSON Formatter", // virgola finale
]
}Supporto per formattazione e parsing
| Scenario | JSON5 | JSONC | Librerie / strumenti consigliati |
|---|---|---|---|
| Browser | Polyfill JSON5.parse(), Prettier con parser json5 integrato (>= v1.13) | Supporto nativo settings.json di VS Code | — |
| Node.js | Pacchetto npm json5 | comment-json, jsonc-parser | Supportano formattazione CLI e parsing AST |
| IDE | Estensioni VS Code, WebStorm | VS Code nativo, plugin WebStorm | Prettier può unificare la formattazione |
| CI / Lint | eslint-plugin-json5 | eslint-plugin-jsonc | Integra con Husky e lint-staged |
| Strumento online | Go Tools JSON Formatter (abbellisce e valida JSON5/JSONC) | Lo stesso | Formattatore JSON |
Formattazione veloce in VS Code
Aggiungi a settings.json:
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}Poi premi Alt + Shift + F per abbellire qualsiasi file JSONC.
File di configurazione del mondo reale
JSON5 e JSONC sono già ampiamente usati in file di configurazione che incontri ogni giorno. Ecco esempi concreti:
TypeScript (tsconfig.json — JSONC)
{
// La modalità strict cattura più bug a tempo di compilazione
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "ESNext",
"outDir": "./dist",
// Alias di percorso per import più puliti
"paths": {
"@/*": ["./src/*"],
"@tests/*": ["./tests/*"],
},
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"],
}tsconfig.json di TypeScript usa JSONC nativamente — commenti e virgole finali funzionano fuori dalla scatola. È uno dei file JSONC più comuni in qualsiasi progetto JavaScript/TypeScript.
ESLint Flat Config (eslint.config.json — JSONC)
{
"rules": {
// Avvisa su console.log, ma permetti console.error
"no-console": ["warn", { "allow": ["error", "warn"] }],
"semi": ["error", "always"],
"quotes": ["error", "double"],
}
}Babel (babel.config.json5 — JSON5)
{
// Apici singoli e chiavi senza virgolette lo rendono più leggibile
presets: [
['@babel/preset-env', {
targets: '> 0.25%, not dead',
modules: false, // Lascia che il bundler gestisca i moduli
}],
],
plugins: [
'@babel/plugin-transform-runtime',
],
}Impostazioni workspace di VS Code (.vscode/settings.json — JSONC)
{
// Preferenze editor
"editor.fontSize": 14,
"editor.tabSize": 2,
"editor.formatOnSave": true,
// Override specifici per linguaggio
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
}Suggerimenti pratici e avvertenze
1. Converti prima della produzione
I browser richiedono ancora JSON stretto per JSON.parse. Usa il tooling di build per rimuovere commenti e virgole finali:
// Script di build Node.js: converti config JSON5 in JSON stretto
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';
const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));Per i bundler, usa rollup-plugin-json5 o vite-plugin-json5 per gestire la conversione automaticamente durante la build.
2. Sicurezza e affidabilità
La permissività può nascondere campi indesiderati. Valida sempre la configurazione con JSON Schema o zod prima di consumarla:
// Valida la forma della config con zod dopo il parsing
import { z } from 'zod';
import JSON5 from 'json5';
const ConfigSchema = z.object({
port: z.number().min(1).max(65535),
host: z.string(),
debug: z.boolean().default(false),
});
const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Lancia se non valido3. Convenzioni di team
- Dichiara nel README che
*.json5è solo per le config; i pacchetti rilasciati dovrebbero spedire.jsonstretto. - Standardizza le regole di Prettier per evitare diff rumorosi.
- Usa
.editorconfigper imporre indentazione coerente tra file JSON, JSON5 e JSONC.
4. Prestazioni
Analizzare JSON5/JSONC aggiunge dipendenze e leggero overhead — va bene per CLI e dev tooling, ma misura per la produzione. Il pacchetto npm json5 è ~8 KB minificato, e il parsing è circa 2-5x più lento del nativo JSON.parse. Per file di configurazione caricati una volta all’avvio, è trascurabile. Per percorsi caldi che analizzano migliaia di oggetti al secondo, attieniti al JSON stretto.
Domande frequenti
Qual è la differenza tra JSON5 e JSONC?
JSON5 estende JSON con sintassi simile a JavaScript: chiavi senza virgolette, virgole finali, commenti su una riga e a blocco, numeri esadecimali e stringhe multilinea. JSONC è più semplice — aggiunge solo commenti su una riga (//) e a blocco (/* */) al JSON standard. Scegli JSONC per file di config dove i commenti bastano; scegli JSON5 quando hai bisogno di sintassi più ricca.
Posso usare JSON5 o JSONC nelle API di produzione?
No — JSON5 e JSONC sono progettati per file di configurazione, non per scambio dati. Le API dovrebbero usare JSON standard (RFC 8259) per la massima interoperabilità. Riserva JSON5/JSONC per file di config locali come tsconfig.json, .vscode/settings.json o configurazione di ambiente dove la leggibilità umana conta più del parsing macchina.
VS Code supporta JSON5 nativamente?
VS Code supporta JSONC nativamente (i suoi file di impostazioni usano JSONC), ma non supporta JSON5 fuori dalla scatola. Per JSON5, installa un’estensione dedicata come “JSON5 syntax” dal marketplace VS Code. Puoi anche associare i file .json5 alla modalità linguaggio JSON5 nelle tue impostazioni.
Come converto JSON5 in JSON standard?
Usa il pacchetto npm json5: JSON5.parse() legge JSON5, poi JSON.stringify() produce JSON standard. Per uso CLI, esegui npx json5 < input.json5 > output.json. Strumenti online come il nostro JSON Formatter possono anche validare l’output convertito per assicurare la correttezza.
JSONC è la stessa cosa di JSON con commenti?
Sì — JSONC sta per “JSON with Comments” ed è il formato usato da VS Code, TypeScript (tsconfig.json) e altri strumenti Microsoft. Segue la spec JSON standard con la sola aggiunta di commenti // e /* */. I parser rimuovono i commenti prima dell’elaborazione, quindi la struttura dati risultante è identica al JSON standard.
Per più strumenti per sviluppatori basati su browser inclusi codifica Base64, generazione di hash e conversione di timestamp, vedi la nostra Guida agli strumenti essenziali per sviluppatori.
Riepilogo
Bilanciare leggibilità e rigore è una classica lotta degli sviluppatori. JSON5 e JSONC migliorano l’esperienza di scrittura, e con la giusta pipeline di build e validazione, puoi godere dei vantaggi del “JSON permissivo” in sicurezza.