Convertire YAML in NDJSON

NDJSON è JSON con una regola sui ritorni a capo: un valore completo per riga, senza virgole, senza parentesi che racchiudono tutto. Per produrlo, qualcosa deve decidere dove finisce un record e dove inizia il successivo, e l’unica cosa in un file YAML che lo dice è una sequenza al livello superiore. Un documento che comincia con un elenco di trattini si converte in una riga per trattino.

Tutto il resto è una riga sola. Una mappatura alla radice è un unico valore per quanto sia annidato al suo interno, quindi un manifest Kubernetes, un file compose o una configurazione applicativa escono come una riga di svariati kilobyte. Non è un errore e di solito non è ciò che voleva chi ha convertito, motivo per cui è la prima cosa detta in questa pagina piuttosto che una nota a piè di pagina.

Se i record che cercate sono annidati sotto una chiave — una chiave users che contiene una lista, una chiave events che contiene una lista — la conversione non entrerà a cercarli. Guarda solo la radice e nient’altro. La correzione è portare quella lista in cima al documento prima di convertire, che in un editor significa eliminare la prima riga e togliere un livello di indentazione al resto.

L’alternativa è convertire prima in JSON e usare jq sia per selezionare sia per trasformare in stream: estrarre l’array ed emetterlo un elemento per riga è una singola espressione. È la strada migliore quando l’estrazione si ripeterà, perché è scriptabile, e questo convertitore è la strada migliore quando succede una volta sola.

Gli ancoraggi YAML permettono di definire un blocco una volta e referenziarlo molte volte, e il parser risolve ogni alias in una copia completa prima che qualcosa venga scritto. L’NDJSON è quindi più grande dello YAML, a volte considerevolmente.

Per uno stream non è un costo, è il requisito. Un consumer di NDJSON legge una riga alla volta e potrebbe non aver mai visto le altre — è proprio lo scopo del formato, ed è ciò che permette a un loader di dividere un file fra più worker o di riprendere dopo un fallimento. Una riga che facesse riferimento a una definizione su una riga precedente romperebbe esattamente le condizioni che il formato esiste per sopravvivere.

Uno stream YAML separato da marcatori --- è, concettualmente, già NDJSON: un documento per record, in ordine. È la corrispondenza strutturale più vicina in tutta questa famiglia di formati, ed è l’unico input che questa conversione rifiuta, perché il parser legge un singolo documento e si ferma quando ne trova un secondo.

La soluzione è una modifica testuale piuttosto che uno strumento. Sostituite ogni --- con un marcatore di elemento di lista di primo livello e indentate i documenti sotto di esso, e il file si converte esattamente nello stream previsto. Su un file grande, un comando sed una tantum lo fa; su pochi documenti, basta un editor.

NDJSON è il formato di interscambio degli strumenti orientati alle righe da circa il 2013, e le destinazioni vogliono cose leggermente diverse. BigQuery e Snowflake accettano JSON delimitato da newline direttamente come formato di caricamento. jq lo legge senza alcun flag e lo riscrive con l’opzione compatta. pandas lo legge con un argomento lines.

Elasticsearch è l’eccezione su cui si inciampa. La sua API bulk ha la forma di NDJSON ma si aspetta una riga d’azione prima di ogni documento, quindi un file di record semplici viene rifiutato. Interlacciare le righe d’azione è un passaggio jq o awk, e deliberatamente non viene fatto qui, perché la riga d’azione nomina un indice e un’operazione che solo voi conoscete.

Ogni riga è JSON compatto: nessuna indentazione, nessuno spazio dopo i due punti, chiavi nell’ordine in cui le aveva lo YAML. Il file è UTF-8 e termina con un a capo, cosa che la maggior parte dei loader richiede e alcuni tollerano silenziosamente.

I tipi vengono dal parser YAML, non da chi scrive. Sotto YAML 1.2 una data non tra virgolette resta una stringa, quindi un campo data arriva come testo piuttosto che come qualcosa che un loader riconoscerebbe come timestamp senza un aiuto di schema. Gli interi grandi sono il pericolo silenzioso: un identificativo scritto 9223372036854775807 esce come 9223372036854776000, perché i numeri JSON sono double IEEE. Metteteli tra virgolette nello YAML prima di convertire.

Una lista i cui elementi non condividono le stesse chiavi si converte senza problemi, e ogni riga porta solo le chiavi che aveva il suo record. È un vantaggio reale rispetto a convertire gli stessi dati in CSV, dove le colonne devono essere l’unione di ogni record e le celle mancanti devono essere riempite con qualcosa.

Se la destinazione è altrettanto flessibile è un’altra questione. Un archivio schema-on-read accetta righe irregolari senza problemi; un loader per tabelle con schema fisso rifiuterà o azzererà i campi imprevisti. Conviene scorrere le prime e le ultime righe di un output grande per vedere quanto varia la forma lungo il file.

I commenti YAML vengono eliminati, e NDJSON non ha dove metterli: è JSON per riga, e JSON non ha una sintassi per i commenti. Non c’è nemmeno una riga di intestazione, nessuna dichiarazione di schema e nessun blocco di metadati, quindi il file porta solo record e nient’altro.

Quell’assenza è deliberata nel formato e va rispettata nella pipeline. Se il caricamento deve conoscere una fonte, un identificativo di batch o una versione di schema, appartiene a un campo su ogni record o al nome del file, non a un preambolo — qualsiasi cosa in cima a un file NDJSON è un record, e un loader proverà a leggerla come tale.

Se lo YAML è configurazione piuttosto che dati, questa conversione non ha nulla da offrire. Una riga di JSON minificato è peggiore dello YAML sotto ogni aspetto a cui una persona tiene, e nessun consumer di stream voleva un file di configurazione. Convertite in JSON se vi serve leggibile da macchina, e lasciate lo YAML così com’è altrimenti.

La coppia vale la pena quando il file è genuinamente una lista — record esportati, fixture, un log di eventi scritto a mano, un dataset di seed — e la destinazione legge righe. In quel caso la conversione è istantanea, avviene interamente nel vostro browser, e l’unica cosa da controllare resta la prima riga e l’ultima.