Strumenti per sviluppatori · JSON formattatore e validatore
Perché JSON non ha commenti: la decisione di progettazione e le sue soluzioni alternative
· Sfondo
json standard convalida
I commenti sono stati rimossi deliberatamente da JSON. Questo post spiega il ragionamento, perché ogni tentativo di aggiungerli nuovamente ha creato un nuovo formato e quali sono le tue opzioni quando un file di configurazione ha davvero bisogno di una nota.
Il commento che ha rotto il build
Il commento che ha interrotto la compilazione: una nota utile aggiunta a una configurazione JSON e a un parser che si fermava alla prima barra. L'autore potrebbe aver copiato un pattern da JavaScript o da un editor compatibile con JSONC, mentre lo strumento di distribuzione utilizza JSON rigoroso. L'evidenziazione della sintassi può far sembrare legittima la nota anche se il consumatore rifiuta il primo indicatore di commento.
I commenti vengono rifiutati perché la barra non è un token JSON in cui lo scanner prevede un valore o un membro. ToolAcre non rimuove silenziosamente la sintassi JSONC o JSON5. Una proprietà convenzionale a forma di commento è un dato ordinario e può violare uno schema dell'applicazione anche se la sintassi rigorosa JSON lo accetta. Affermazioni storiche non supportate sul design di JSON vengono omesse o corrette anziché presentate come fatti accertati senza prove primarie o una fonte di standard tracciabili disponibile per la verifica.
Motivo per cui Crockford ha rimosso i commenti
Motivo di Crockford per la rimozione dei commenti: una spiegazione successiva afferma che i commenti erano stati utilizzati per trasportare direttive di analisi, minando l'interoperabilità tra le implementazioni. La conseguenza progettuale rilevante è che lo standard JSON non ha token di commento. Le affermazioni su motivazioni private, cronologia esatta o risposta universale del settore richiedono fonti storiche non fornite da questo archivio.
Di conseguenza, le affermazioni storiche non supportate vengono qui omesse o corrette. Lo standard osservabile e il comportamento del parser sono sufficienti: strict JSON scambia dati attraverso sei tipi di valore e due contenitori, senza un canale di annotazione. Questo vincolo impedisce a un destinatario di assegnare un significato operativo al testo che un altro destinatario ignora, ma rende anche JSON meno comodo per la configurazione gestita manualmente.
Ciò che un validatore riporta su un commento
Ciò che un validatore riporta su un commento: `//` e `/* */` non sono nella grammatica, quindi l'errore si verifica sulla prima barra con una riga e una colonna. Lo scanner non si oppone alle parole nella nota. Non può iniziare alcun valore JSON, nome membro o separatore valido con `/` in quella posizione.
Per `{"port":8080, // solo locale "secure":false}`, la virgola è valida e il token legale successivo deve essere un nome di proprietà tra virgolette o la parentesi graffa di chiusura. La barra viola tale aspettativa. La rimozione solo della nota lascia un separatore valido e il membro successivo; l'eliminazione della punteggiatura vicina può creare un secondo errore. Riconvalidare l'esatto output rigoroso dopo ogni modifica.
I formati che hanno aggiunto commenti
I formati che hanno aggiunto commenti: JSONC consente commenti sulla sintassi JSON altrimenti familiare, mentre JSON5 aggiunge comodità come chiavi identificative senza virgolette e virgole finali. Hjson enfatizza l'editing umano con una sintassi rilassata aggiuntiva. YAML ha una propria grammatica, inclusi i commenti, e non è semplicemente JSON con l'aggiunta di annotazioni.
L'accettazione è specifica del consumatore: le impostazioni dell'editor e la configurazione di TypeScript possono utilizzare parser con tolleranza ai commenti, mentre il manifest di un pacchetto o il corpo API può richiedere un rigoroso JSON. Kubernetes consuma comunemente YAML o JSON in base ai suoi strumenti. Nominare il formato effettivo nella documentazione e nella gestione dei file; l'eliminazione delle estensioni o la chiamata di ogni notazione di oggetto "JSON" nasconde i limiti di compatibilità.
Soluzioni alternative all'interno di strict JSON
Soluzioni alternative all'interno del rigido JSON: una chiave convenzionale `_comment` o `//` memorizza la spiegazione come un normale membro di stringa. Sopravvive all'analisi rigorosa perché sia la chiave che il valore utilizzano token standard. Più note necessitano di chiavi univoche o di un array, poiché i nomi dei membri duplicati sono inaffidabili e potrebbero essere compressi dai parser.
La soluzione alternativa modifica il modello di dati. Uno schema con `additionalProperties: false` può rifiutare l'annotazione e un'applicazione può persistere o trasmetterla come configurazione reale. La documentazione esterna, un README adiacente o uno schema `description` spesso forniscono un canale di spiegazione più sicuro. Utilizzare i membri sotto forma di commento solo quando ogni consumatore li consente e li ignora esplicitamente.
Esempio realizzato: un file di impostazioni annotato
Esempio realizzato: un file di impostazioni con annotazioni: inizia con una fonte JSONC contenente `// seconds before retry` sopra `"timeout":30`. Se la destinazione accetta solo JSON, utilizza un parser che comprenda JSONC per produrre dati e quindi serializza tali dati come rigoroso JSON. L'artefatto distribuito diventa `{"timeout":30}` mentre l'origine mantenuta mantiene la sua spiegazione.
Non rimuovere i commenti con un'espressione regolare. Le sequenze di barre possono apparire legittimamente all'interno di stringhe come gli URL e i modelli di blocco dei commenti possono estendersi su righe in modi in cui la sostituzione testuale non riesce a gestire correttamente. Mantieni distinti l'origine e l'artefatto generato, convalida il risultato rigoroso e organizza la rigenerazione nella build. Ciò preserva le note dell'autore senza pretendere che il parser ricevente le supporti.
Ciò che questo non copre
Cosa non copre: come configurare i singoli parser per accettare commenti, che è specifico dello strumento e cambia spesso. Un'opzione permissiva in una libreria non altera la grammatica JSON né garantisce che un altro servizio accetterà lo stesso testo. Controlla il parser, la versione e la destinazione anziché fare affidamento sulla visualizzazione di un editor.
Questo articolo evita inoltre affermazioni non supportate su quando esattamente i commenti sono stati rimossi, chi ha adottato per primo ciascuna soluzione alternativa o se una decisione di progettazione da sola ha causato la popolarità di JSON. Tali affermazioni storiche necessitano di fonti primarie indipendenti. Qui vengono omessi o corretti; la conclusione supportata è limitata all'attuale rigorosa sintassi, al comportamento del repository e alle differenze operative tra i formati denominati.
Conclusione: JSON è un formato di interscambio di dati, non un linguaggio di configurazione
Conclusione: JSON è un formato di interscambio di dati, non un linguaggio di configurazione ricco di commenti e il validatore mostra esattamente dove una nota infrange la grammatica rigorosa. Quando gli esseri umani hanno bisogno di annotazioni, scegli un formato supportato ufficialmente dallo strumento di consumo o mantieni una fonte annotata che generi un artefatto rigoroso separato. Non dare per scontato che i commenti verranno ignorati in modo innocuo.
Se il rigoroso JSON è obbligatorio, sposta la spiegazione nella documentazione o utilizza metadati approvati dallo schema, quindi convalida il documento finale. ToolAcre segnala intenzionalmente la prima barra invece di eliminare silenziosamente il materiale, poiché la conversione silenziosa potrebbe modificare le stringhe o nascondere una mancata corrispondenza del formato. Il contesto storico dovrebbe rimanere ugualmente disciplinato: le affermazioni non supportate vengono omesse o corrette, mentre la sintassi osservabile e il comportamento del parser portano alla conclusione.