Di Jerry Fan

Tutorial JSONL: creare, leggere e convertire file JSONL

Un tutorial passo dopo passo con tutto ciò che ti serve per lavorare con i file JSONL (JSON Lines), con esempi di codice in Python e JavaScript e comandi da eseguire con gli strumenti CLI.

Cos'è JSONL?

JSONL (JSON Lines) è un formato di testo leggero in cui ogni riga contiene un valore JSON valido e indipendente. A differenza del JSON standard, che racchiude tutti i dati in un unico array o oggetto, JSONL memorizza un record per riga, usando il carattere di fine riga (\n) come separatore.

Questa struttura rende JSONL ideale per elaborare grandi dataset in streaming, aggiungere record senza riscrivere il file ed elaborare i dati in parallelo. È molto usato da OpenAI per i dataset di fine-tuning, dai sistemi di logging come lo stack ELK e dagli strumenti per i big data come BigQuery e Apache Spark.

example.jsonl
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}

Come creare file JSONL

Creare un file JSONL è semplice: serializza ogni record in una stringa JSON su una sola riga e scrivila nel file, seguita da un carattere di fine riga. Ecco alcuni esempi nei linguaggi più usati.

Python
import json


records = [
    {"id": 1, "name": "Alice", "role": "engineer"},
    {"id": 2, "name": "Bob", "role": "designer"},
    {"id": 3, "name": "Charlie", "role": "manager"},
]


with open("output.jsonl", "w", encoding="utf-8") as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print("Created output.jsonl with", len(records), "records")
JavaScript / Node.js
import { writeFileSync } from 'fs';


const records = [
  { id: 1, name: 'Alice', role: 'engineer' },
  { id: 2, name: 'Bob', role: 'designer' },
  { id: 3, name: 'Charlie', role: 'manager' },
];


const jsonl = records
  .map(record => JSON.stringify(record))
  .join('\n');


writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created output.jsonl with ${records.length} records`);

Creazione manuale con un editor di testo

Puoi creare file JSONL anche con un qualsiasi editor di testo. Basta scrivere un oggetto JSON valido per riga, senza virgole tra una riga e l’altra, e salvare il file con estensione .jsonl. Assicurati che ogni riga contenga un valore JSON completo e valido.

Come leggere file JSONL

Ogni riga contiene un valore JSON indipendente: per leggere un file JSONL basta quindi scorrere le righe. Ecco gli approcci più comuni.

Python
import json


with open("data.jsonl", "r", encoding="utf-8") as f:
    for line_number, line in enumerate(f, 1):
        line = line.strip()
        if not line:
            continue  # skip empty lines
        record = json.loads(line)
        print(f"Line {line_number}: {record['name']} - {record['role']}")
JavaScript / Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.jsonl', 'utf-8'),
});


let lineNumber = 0;
for await (const line of rl) {
  if (!line.trim()) continue; // skip empty lines
  lineNumber++;
  const record = JSON.parse(line);
  console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);
}
Riga di comando (grep / jq)
# View first 10 lines
head -n 10 data.jsonl


# Count total records
wc -l data.jsonl


# Pretty-print each line with jq
cat data.jsonl | jq .


# Filter records where role is "engineer"
cat data.jsonl | jq 'select(.role == "engineer")'


# Extract only the name field
cat data.jsonl | jq -r '.name'


# Search for lines containing a keyword
grep '"Alice"' data.jsonl

Come convertire JSON in JSONL

Per convertire un normale array JSON in JSONL, basta scrivere ogni elemento su una riga separata. È una delle operazioni più comuni quando lavori con JSONL.

Python
import json


# Read JSON array
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)  # expects a JSON array


# Write as JSONL
with open("data.jsonl", "w", encoding="utf-8") as f:
    for record in data:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print(f"Converted {len(data)} records from JSON to JSONL")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


// Read JSON array
const data = JSON.parse(readFileSync('data.json', 'utf-8'));


// Write as JSONL
const jsonl = data
  .map(record => JSON.stringify(record))
  .join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Converted ${data.length} records from JSON to JSONL`);

Converti direttamente online

Non vuoi scrivere codice? Usa il nostro convertitore online gratuito da JSON a JSONL: incolla o carica il file e convertilo subito.

Come convertire CSV in JSONL

La conversione da CSV a JSONL trasforma ogni riga in un oggetto JSON, usando le intestazioni del CSV come nomi dei campi. È utile per migrare dati tabulari verso un formato adatto allo streaming o al machine learning.

Python
import csv
import json


with open("data.csv", "r", encoding="utf-8") as csv_file:
    reader = csv.DictReader(csv_file)
    with open("data.jsonl", "w", encoding="utf-8") as jsonl_file:
        for row in reader:
            jsonl_file.write(json.dumps(row, ensure_ascii=False) + "\n")


print("Converted CSV to JSONL successfully")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


const csv = readFileSync('data.csv', 'utf-8');
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');


const jsonl = lines.slice(1).map(line => {
  const values = line.split(',');
  const obj = {};
  headers.forEach((h, i) => obj[h.trim()] = values[i]?.trim());
  return JSON.stringify(obj);
}).join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log('Converted CSV to JSONL successfully');

Converti CSV online

Converti subito i file CSV in JSONL con il nostro strumento online gratuito, senza scrivere codice.

Buone pratiche per lavorare con JSONL

1

Usa la codifica UTF-8 per tutti i file JSONL: garantisce la compatibilità tra piattaforme e il supporto per i caratteri internazionali.

2

Scrivi esattamente un oggetto JSON per riga. Non distribuire mai un oggetto JSON su più righe e non inserire più oggetti nella stessa riga.

3

Non aggiungere virgole tra le righe. A differenza degli array JSON, JSONL usa il carattere di fine riga come unico delimitatore.

4

Valida ogni riga separatamente: deve contenere un valore JSON completo e valido. Usa un validatore JSONL per individuare subito gli errori di sintassi.

5

Leggi i file di grandi dimensioni in streaming. Anziché caricare tutto il file in memoria, elaboralo riga per riga con readline (Node.js) o iterando sulle righe del file (Python).

6

Mantieni una struttura coerente tra i record. JSONL consente di usare schemi diversi per ogni riga, ma una struttura uniforme semplifica molto l’elaborazione dei dati.

7

Evita spazi e tabulazioni a fine riga. Verifica che le righe non contengano spazi o tabulazioni superflui che potrebbero causare problemi di parsing.

8

Termina il file con un carattere di fine riga. Aggiungerlo dopo l’ultimo record aiuta strumenti come wc e cat a gestire correttamente il file.

Errori comuni con JSONL

Racchiudere i record in un array
Sbagliato
[
  {"name":"Alice"},
  {"name":"Bob"}
]
Corretto
{"name":"Alice"}
{"name":"Bob"}

JSONL non è un array JSON. Non racchiudere le righe tra parentesi quadre e non separarle con virgole: ogni riga è indipendente.

Inserire virgole tra le righe
Sbagliato
{"name":"Alice"},
{"name":"Bob"},
Corretto
{"name":"Alice"}
{"name":"Bob"}

In JSONL non sono ammesse virgole alla fine delle righe o tra una riga e l’altra. L’unico separatore è il carattere di fine riga.

Distribuire gli oggetti JSON su più righe
Sbagliato
{
  "name": "Alice",
  "age": 30
}
Corretto
{"name":"Alice","age":30}

Ogni oggetto JSON deve occupare una sola riga. Il JSON formattato con indentazione e interruzioni di riga non è JSONL valido.

Omettere l’escape dei caratteri speciali
Sbagliato
{"text":"She said "hello""}
Corretto
{"text":"She said \"hello\""}

Le virgolette e i caratteri speciali all’interno delle stringhe JSON richiedono l’escape con il backslash. Le virgolette senza escape causano un errore nel parser JSON.

Prova i nostri strumenti gratuiti per JSONL

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Non serve caricare i file su un server: la privacy è garantita al 100%.

Domande frequenti

Riferimenti