Di Jerry Fan

JSONL vs NDJSON: qual è la differenza?

Una guida completa al confronto tra JSONL (JSON Lines) e NDJSON (Newline Delimited JSON): due nomi per un formato pressoché identico, con alcune piccole differenze che vale la pena conoscere.

JSONL vs NDJSON: confronto rapido

CaratteristicaJSONL (JSON Lines)NDJSON
Nome completoJSON LinesNewline Delimited JSON
Estensione del file.jsonl.ndjson
Specificajsonlines.org (informale)github.com/ndjson/ndjson-spec (specifica informale)
OrigineConvenzione nata nella community e diffusa dagli strumenti di data scienceProposto da Chris Olah, Thorsten Ball e altri
Separatore di riga\n (newline)\n (newline)
Tipo MIMEapplication/jsonl (non ufficiale)application/x-ndjson
Supporto allo streamingSì, riga per rigaSì, riga per riga
AdozioneOpenAI, Hugging Face, ecosistema ML/AIElasticsearch, Apache Spark, data engineering

Cos'è JSONL (JSON Lines)?

JSONL, abbreviazione di JSON Lines, è un formato testuale in cui ogni riga contiene un singolo valore JSON valido. Le righe sono separate da caratteri di fine riga (\n). Il formato si è diffuso grazie alle community di machine learning e data science ed è descritto da una specifica informale su jsonlines.org.

I file JSONL usano l'estensione .jsonl. Il formato è diventato lo standard per i dati di addestramento AI e ML: OpenAI richiede file .jsonl per il fine-tuning e i dataset di Hugging Face usano comunemente il formato JSON Lines.

data.jsonl
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}

Cos'è NDJSON (Newline Delimited JSON)?

NDJSON, ovvero Newline Delimited JSON, è un formato in cui ogni riga contiene un valore JSON valido e le righe sono separate da caratteri di fine riga. La specifica, disponibile su github.com/ndjson/ndjson-spec, è stata formalizzata per offrire uno standard più strutturato per i dati JSON organizzati per righe.

I file NDJSON usano l'estensione .ndjson e il tipo MIME registrato application/x-ndjson. Il formato è molto diffuso nel data engineering, nell'elaborazione dei log e nelle applicazioni di streaming: lo usano Elasticsearch, Apache Spark e molte API HTTP che trasmettono dati in streaming.

data.ndjson
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}

JSONL e NDJSON sono lo stesso formato?

In pratica, sì: JSONL e NDJSON sono formati funzionalmente identici. Entrambi memorizzano un valore JSON per riga, con le righe separate da caratteri di fine riga (\n). Un file .jsonl e un file .ndjson che contengono gli stessi dati sono completamente intercambiabili: qualsiasi strumento in grado di leggere uno dei due formati può leggere anche l’altro.

Le differenze riguardano solo il nome, le community che li adottano e le convenzioni sui metadati. JSONL (JSON Lines) è nato nella community di data science e machine learning, mentre NDJSON (Newline Delimited JSON) è stato formalizzato dalla community di data engineering e streaming web. Pensa ai termini inglesi "movie" e "film": indicano la stessa cosa, ma in ambienti diversi si preferisce un nome o l’altro.

Le differenze più rilevanti sono l'estensione del file (.jsonl vs .ndjson) e il tipo MIME. NDJSON ha un tipo MIME più riconosciuto (application/x-ndjson), usato per lo streaming HTTP, mentre i file JSONL sono lo standard nei flussi di lavoro AI/ML. Per scegliere, segui le convenzioni del tuo ecosistema.

Differenze principali tra JSONL e NDJSON

1. Specifica e riferimento

JSONL

È definito su jsonlines.org da una specifica breve e informale. Le regole sono semplici: ogni riga contiene un valore JSON valido, le righe sono separate da '\n' e la codifica UTF-8 è consigliata.

NDJSON

È definito su github.com/ndjson/ndjson-spec da una specifica leggermente più formale. NDJSON richiede esplicitamente che ogni riga contenga un valore JSON valido e che il separatore di riga sia '\n' (non '\r\n'); è inoltre consigliato un carattere di fine riga al termine del file.

2. Estensione del file

JSONL

Usa l'estensione .jsonl, lo standard per i file di fine-tuning di OpenAI, i dataset di Hugging Face e la maggior parte degli strumenti ML/AI. GitHub e VS Code riconoscono i file .jsonl e ne evidenziano la sintassi.

NDJSON

Usa l'estensione .ndjson, comune negli strumenti di data engineering, nelle API bulk di Elasticsearch e nelle risposte HTTP in streaming. Molti editor supportano anche l'evidenziazione della sintassi per i file .ndjson.

3. Tipo MIME

JSONL

Non ha un tipo MIME registrato ufficialmente. Tra i tipi non ufficiali più comuni ci sono application/jsonl e application/json-lines. In pratica, molti sistemi usano application/jsonl oppure ricorrono ad application/json.

NDJSON

Usa il tipo MIME application/x-ndjson, più riconosciuto in ambito HTTP e utilizzato da Elasticsearch, dallo standard di streaming della Fetch API e da vari framework web per le risposte in streaming.

4. Diffusione nelle community e negli ecosistemi

JSONL

È il formato predominante nell'ecosistema AI/ML. OpenAI, Anthropic, Google Gemini, Hugging Face e la maggior parte dei framework ML usano .jsonl. Nel complesso, nella community degli sviluppatori il termine 'JSONL' è più conosciuto e cercato più spesso.

NDJSON

È il formato preferito nel data engineering e nei sistemi backend. Elasticsearch, Apache Spark, PostgreSQL COPY e molti strumenti di aggregazione dei log usano NDJSON. Il pacchetto npm ndjson conta milioni di download ogni settimana.

Quando usare JSONL e quando NDJSON

JSONLUsa .jsonl quando:
  • Prepari dati di addestramento per il fine-tuning con OpenAI, Anthropic o altri LLM
  • Lavori con i dataset di Hugging Face
  • Crei pipeline ML e ti occupi di preprocessing dei dati
  • Il tuo team o la documentazione usa il termine 'JSON Lines'
  • Carichi file su piattaforme AI/ML che richiedono l'estensione .jsonl
  • Lavori in ambienti di data science basati su Python
NDJSONUsa .ndjson quando:
  • Trasmetti dati JSON in streaming su HTTP (Server-Sent Events, streaming con fetch)
  • Lavori con l'API bulk di Elasticsearch
  • Crei pipeline di dati con Apache Spark o strumenti simili
  • Imposti gli header Content-Type (application/x-ndjson)
  • La tua infrastruttura o il tuo team segue la convenzione NDJSON
  • Lavori con librerie di streaming per Node.js

Esempi di codice: leggere JSONL e NDJSON

Leggere un file .jsonl (Python)
# Reading JSONL - exactly the same as reading NDJSON
import json


with open('data.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line.strip())
        print(record['text'])


# Output:
# Hello world
# How are you?
# Goodbye
Leggere un file .ndjson (JavaScript/Node.js)
// Reading NDJSON - exactly the same as reading JSONL
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.ndjson')
});


for await (const line of rl) {
  const record = JSON.parse(line);
  console.log(record.text);
}


// Output:
// Hello world
// How are you?
// Goodbye

Visualizza subito i file JSONL e NDJSON

Apri file .jsonl e .ndjson fino a 1GB nel browser. Non servono upload né registrazione: funziona con entrambi i formati senza problemi.

Domande frequenti

Riferimenti