Che cos’è un file NDJSON?

NDJSON è un formato di testo semplice che si apre in qualsiasi editor. Si usa per spostare dati fra programmi e lo streaming.

L’estensione è .ndjson e il nome per esteso è Newline-Delimited JSON. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Risale al 2013.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

NDJSON conserva il suo contenuto esattamente. Risalvarlo non cambia nulla, quindi puoi aprirlo, modificarlo e risalvarlo quante volte vuoi senza accumulare danni: è questo che ne fa un formato di lavoro e non di consegna.

NDJSON può contenere una disposizione che gli permette di partire prima di essere arrivato per intero.

Conta soprattutto in conversione: quello che la destinazione non può contenere viene lasciato cadere, di solito senza avvisare.

NDJSON non ha una sintassi per i commenti. Tutto ciò che spiega deve vivere fuori dal file, ed è bene saperlo prima di sceglierlo per qualcosa che una persona modificherà a mano.

jq e pandas lo leggono, e così fanno quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Nessun browser lo legge.

È di gran lunga il motivo più comune per convertirlo: non che il formato sia scadente, ma che il posto in cui vuoi mostrare il file non sappia leggerlo.

NDJSON è pensato per essere aperto e modificato. Tieni il file in questo formato per tutto il tempo in cui il lavoro va avanti, ed esporta da lì ogni volta che serve una copia finita.

È il problema per cui esiste il formato. Un documento JSON è valido solo quando arriva la parentesi di chiusura, quindi un parser a cui viene consegnato un array di record da dieci gigabyte deve leggere tutti e dieci i gigabyte in memoria prima di poter restituire il primo. Per uno stream di log che non finisce mai, non può mai restituire nulla del tutto.

NDJSON elimina l’array. Ogni riga è un oggetto JSON completo e indipendente, terminato da un ritorno a capo e senza nulla intorno. Un lettore prende una riga, la analizza, la elabora e la dimentica — quindi l’uso di memoria è la dimensione del record più grande invece che la dimensione del file, e un processo può iniziare a lavorare sul primo record immediatamente.

Aggiungere un record a un array JSON significa riscrivere il file: la parentesi di chiusura è alla fine, e qualcosa deve andare prima di essa. Aggiungere un record a un file NDJSON significa scrivere una riga.

È ciò che lo rende il formato naturale per qualunque cosa si accumuli nel tempo — log applicativi, stream di eventi, tracce di audit, dati raccolti, telemetria. È anche ciò che lo rende sicuro sotto concorrenza in un modo in cui un array JSON non lo è: una singola scrittura di una riga sotto la dimensione di scrittura atomica del sistema non si intreccerà con la riga di un altro scrittore, quindi diversi processi possono aggiungere allo stesso file senza corromperlo.

Un array JSON troncato da un crash o da un disco pieno è invalido nella sua interezza — una parentesi mancante e un parser rifiuta l’intero file, compreso il 99 per cento arrivato perfettamente.

Un file NDJSON troncato a metà scrittura perde solo l’ultima riga e nient’altro. Ogni riga completa prima di essa si analizza ancora, e un lettore può saltare quella rotta e continuare. Per dati raccolti in settimane e memorizzati su hardware che alla fine si guasterà, quella differenza non è accademica.

Spedizione di log e osservabilità: l’API bulk di Elasticsearch, Logstash, Fluentd, Vector e la maggior parte delle librerie di logging strutturato lo parlano tutte. Esportazioni di dati da API che restituiscono più righe di quante ne stiano in una risposta. Dataset per l’apprendimento automatico, dove i dati di addestramento sono un esempio per riga e il file si legge in un ciclo in streaming.

Anche come formato di trasporto per richieste di lunga durata, dove un server scrive un oggetto JSON per riga man mano che i risultati diventano disponibili e il client li elabora appena arrivano invece di aspettare l’intera risposta.

Un oggetto per riga, e nessun ritorno a capo dentro. Una stringa JSON può legalmente contenere un ritorno a capo con escape e non deve mai contenerne uno letterale — un oggetto formattato su più righe rompe completamente il formato, ed è di gran lunga il modo più comune in cui un file NDJSON viene generato in modo sbagliato.

UTF-8, nessun byte order mark, e un ritorno a capo alla fine dell’ultima riga invece che mancante o con una riga vuota finale. I fine riga dovrebbero essere del tipo a un solo carattere: un ritorno a carrello Windows prima di ogni ritorno a capo è tollerato dalla maggior parte dei lettori e rifiutato da alcuni, esattamente il tipo di guasto intermittente che nessuno si diverte a diagnosticare.

Tre nomi per la stessa cosa. NDJSON è la specifica con un tipo di media; JSON Lines è una descrizione scritta separatamente dello stesso formato identico; JSONL è l’estensione che la gente usa, in particolare nell’apprendimento automatico.

Le differenze fra le specifiche sono cosmetiche — una nota sui fine riga qui, un’estensione permessa là — e nessuno strumento in pratica le distingue. Un file con l’una o l’altra estensione può essere consegnato a qualunque cosa si aspetti l’altra.

In JSON, quando un consumatore vuole un singolo documento: avvolgete le righe in parentesi e unitele con virgole. Banale, e reintroduce il problema di memoria, che è generalmente il motivo per cui il file era NDJSON in primo luogo.

In CSV, quando i dati sono davvero record piatti e qualcuno vuole un foglio di calcolo. La trappola è che il JSON è annidato e il CSV no, quindi gli oggetti annidati vanno appiattiti in nomi di colonna con punti e gli array vanno scartati o uniti — un passaggio con perdita, giusto per il reporting e sbagliato per un archivio.

E in Parquet per qualunque cosa analitica. Un formato colonnare, compresso e tipizzato si legge notevolmente più veloce per le query che le persone eseguono davvero contro dati di eventi, ed è dove un grande archivio NDJSON di solito vuole finire.