Convertire NDJSON in JSON

Un documento JSON è un singolo valore. Un file NDJSON è una sequenza di valori con a capo tra loro, e nessuna buona volontà lo rende un documento — un parser legge il primo oggetto, arriva alla graffa aperta del secondo, e si ferma con un errore di token inatteso. Non è un bug del parser, ed è il motivo per cui questa pagina esiste.

La conseguenza si presenta in luoghi ordinari. Un validatore JSON Schema rifiuta il file. `response.json()` in un browser lancia un'eccezione. Un `import data from "./records.json"` fallisce al momento della build. Un caricatore di configurazione segnala un errore di sintassi sulla riga 2 di un file la cui riga 2 è JSON perfettamente valido. In ogni caso il rimedio è la stessa singola riga di struttura: parentesi quadre attorno a tutto e virgole tra i record.

Ogni riga diventa un elemento di un array di primo livello, nell'ordine del file, ed è vero anche quando la sorgente ha una sola riga — un file a un record produce un array a un elemento invece di un oggetto nudo. L'output è indentato di due spazi per livello e finisce con un a capo.

Poter prevedere la forma conta più di quanto sembri. Significa che uno script che consuma il risultato può indicizzarlo senza controllare cosa è tornato, e significa che la lunghezza dell'array è il numero di righe non vuote della sorgente. Se la sorgente è un file a un solo oggetto e si voleva l'oggetto piuttosto che una lista di uno, quello svolgimento è un passo separato che questa conversione non farà.

La maggior parte delle API non accetta un array nudo. Accettano un oggetto con i record sotto un nome — `{"records": […]}`, `{"data": […]}`, `{"items": […]}` — e spesso con un conteggio o un identificatore di lotto accanto. La conversione produce l'array e si ferma lì, perché inventare un nome di chiave significherebbe indovinare un contratto che non può vedere.

Aggiungerlo dopo è banale e vale la pena farlo deliberatamente piuttosto che a mano in un editor, dove una graffa mancante alla fine di un file grande è facile da fare e tediosa da trovare. `jq '{records: .}' out.json` lo avvolge; `jq '{count: length, records: .}' out.json` lo avvolge con il conteggio che l'endpoint probabilmente vuole anche. Si controlla il nome del campo contro la documentazione dell'API prima di inviare qualcosa, dato che un lotto respinto di solito riporta solo che il corpo era invalido.

Questa è la direzione sicura fuori dall'NDJSON, e vale la pena dirlo chiaramente perché le destinazioni vicine non lo sono. Inviare lo stesso file a CSV, TSV, XLSX o Parquet appiattisce ogni oggetto nidificato in colonne puntate e riconcilia i record contro un unico insieme di colonne. Qui non succede nulla del genere: un record con un oggetto `user` a tre livelli di profondità arriva con quell'oggetto a tre livelli di profondità.

I tipi sopravvivono per lo stesso motivo. Un numero resta un numero, `true` resta un booleano, `null` resta null, e una stringa numerica resta tra virgolette. Nulla viene dedotto, perché nulla ha bisogno di esserlo — la sorgente era già JSON e la destinazione è JSON. L'ordine delle chiavi dentro ogni record è anch'esso conservato, il che rende l'output confrontabile con un'altra esportazione degli stessi dati.

Se una riga qualsiasi non riesce a essere analizzata, non viene scritto nulla. Il messaggio identifica la riga: "Questo file non può essere letto come NDJSON — la riga 3 non è JSON valido." Nessun documento parziale viene prodotto e nessun record viene saltato silenziosamente.

Per questa destinazione quel comportamento vale più di quanto valga per un foglio di calcolo. Una riga finale troncata — la causa abituale, da un processo interrotto a metà scrittura o un file ruotato tagliato a un confine — altrimenti produrrebbe un documento che si analizza, si valida, e a cui manca un numero sconosciuto di record. Cancellare o riparare la riga indicata richiede un comando, e si sa esattamente cosa è stato rimosso. Le righe vuote finali non sono un problema: vengono saltate, incluso l'a capo finale che quasi ogni scrittore lascia.

L'output è stampato in modo leggibile con indentazione di due spazi, quindi un record che occupava una riga densa nella sorgente occupa una riga per ogni valore foglia più le sue graffe. Un file di record piatti con una dozzina di campi ciascuno quindi cresce di circa un fattore dieci righe, e il conteggio dei byte cresce con l'indentazione su ognuna.

Nulla di tutto ciò è dato, e si comprime a quasi nulla sulla rete. Se la destinazione è una persona o un diff, l'indentazione è il punto. Se la destinazione è un campo di caricamento con un limite di dimensione, si passa il risultato attraverso `jq -c .` per ottenere la forma compatta, o si riconsidera se la ricezione avesse davvero bisogno di un documento — molte di quelle che sembra ne abbiano bisogno accetteranno volentieri l'NDJSON se richiesto.

Entrambe le metà di questa conversione sono operazioni a valore intero. Le righe vengono analizzate in un array prima che qualcosa venga scritto, e l'array viene serializzato in un unico passaggio, quindi il costo di picco è la sorgente più la struttura analizzata più la stringa di output. Nulla scorre in streaming, e nulla può — un array non è finito finché il suo ultimo elemento non lo è.

Il tetto gratuito è 100 MB per file e il tetto pratico è la scheda. Decine di megabyte non sono un problema; diverse centinaia di megabyte di record sono dove un browser inizia a faticare, ed è esattamente la dimensione a cui trasformare uno stream in un documento singolo smette comunque di essere una buona idea. NDJSON si divide in sicurezza a qualsiasi confine di riga, quindi `split -l 200000` dà file che convertono ciascuno in modo pulito.

Convertire il risultato indietro restituisce ciò da cui si è partiti. Un array JSON di primo livello viene scritto un elemento per riga, quindi i record, le loro chiavi, l'ordine delle chiavi e i loro tipi tornano tutti invariati. Non c'è alcun passo con perdita in nessuna delle due direzioni da accumulare.

Questo rende la coppia utile come passo di lavoro invece che come migrazione. Si converte in JSON, si esegue il validatore o il controllo dello schema, si corregge ciò di cui si lamenta in un vero editor JSON con corrispondenza delle parentesi, si converte indietro, e si dà lo stream corretto al caricatore che voleva righe fin dall'inizio. L'NDJSON resta il formato di trasporto e il JSON è la forma in cui si lavora.

Se chi riceve accetta input delimitato da a capo, gli si dà quello. I caricamenti bulk di BigQuery, ClickHouse, DuckDB, Elasticsearch e la maggior parte degli spedizionieri di log nominano NDJSON come formato di input proprio perché un singolo array costringe il lettore a tenere tutto in memoria in una volta. Convertire per soddisfare una preferenza piuttosto che un requisito rende il file più grande e il caricamento più lento.

Si tiene l'originale in ogni caso. L'array non ha alcun vantaggio che manchi alle righe eccetto essere un valore unico, e le righe ne hanno diversi che all'array mancano: si aggiungono senza riscrivere, si filtrano con `jq` senza essere caricate intere, e un byte corrotto danneggia un record piuttosto che l'intero documento.

La conversione è puro JavaScript nella pagina. Nessun motore viene scaricato, nessuna richiesta porta il file, non c'è account e non c'è quota giornaliera, e la scheda Rete durante una conversione è il controllo piuttosto che questa frase.

Conta qui perché i file che hanno bisogno di questa conversione sono raramente pubblici. Un'esportazione di eventi, un log di audit, un estratto cliente in viaggio verso un validatore di schema — tutti sono esattamente il materiale che un'organizzazione vieta di incollare in un servizio web. Non c'è nulla da vietare quando nulla viene inviato.