Tutorial de JSONL: cómo crear, leer y convertir archivos JSONL
Un tutorial paso a paso con todo lo que necesitas saber para trabajar con archivos JSONL (JSON Lines). Incluye ejemplos de código en Python y JavaScript, además de ejemplos con herramientas de línea de comandos.
¿Qué es JSONL?
JSONL (JSON Lines) es un formato de texto ligero en el que cada línea contiene un valor JSON válido e independiente. A diferencia del JSON estándar, que agrupa todos los datos en un único array u objeto, JSONL almacena un registro por línea y utiliza caracteres de salto de línea (\n) como separadores.
Esta estructura por líneas hace que JSONL sea ideal para procesar grandes conjuntos de datos en streaming, añadir registros sin reescribir el archivo y procesar datos en paralelo. OpenAI lo utiliza ampliamente para conjuntos de datos de fine-tuning, al igual que sistemas de logs como el stack ELK y herramientas de big data como BigQuery y Apache Spark.
{"id":1,"name":"Alicia","role":"ingeniera"}
{"id":2,"name":"Roberto","role":"diseñador"}
{"id":3,"name":"Carlos","role":"gerente"}Cómo crear archivos JSONL
Crear un archivo JSONL es sencillo: serializa cada registro como una cadena JSON de una sola línea y escríbela seguida de un salto de línea. A continuación tienes ejemplos en los lenguajes más populares.
import json
records = [
{"id": 1, "name": "Alicia", "role": "ingeniera"},
{"id": 2, "name": "Roberto", "role": "diseñador"},
{"id": 3, "name": "Carlos", "role": "gerente"},
]
with open("output.jsonl", "w", encoding="utf-8") as f:
for record in records:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print("Creado output.jsonl con", len(records), "registros")import { writeFileSync } from 'fs';
const records = [
{ id: 1, name: 'Alicia', role: 'ingeniera' },
{ id: 2, name: 'Roberto', role: 'diseñador' },
{ id: 3, name: 'Carlos', role: 'gerente' },
];
const jsonl = records
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Creado output.jsonl con ${records.length} registros`);A mano, con un editor de texto
También puedes crear archivos JSONL con cualquier editor de texto. Escribe un objeto JSON válido por línea, sin comas entre las líneas, y guarda el archivo con la extensión .jsonl. Asegúrate de que cada línea contenga un valor JSON completo y válido.
Cómo leer archivos JSONL
Como cada línea contiene un valor JSON independiente, para leer un archivo JSONL basta con recorrer sus líneas. Estas son las formas más habituales de hacerlo.
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 # saltar líneas vacías
record = json.loads(line)
print(f"Línea {line_number}: {record['name']} - {record['role']}")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; // saltar líneas vacías
lineNumber++;
const record = JSON.parse(line);
console.log(`Línea ${lineNumber}: ${record.name} - ${record.role}`);
}# Ver las primeras 10 líneas
head -n 10 data.jsonl
# Contar total de registros
wc -l data.jsonl
# Imprimir de forma legible cada línea con jq
cat data.jsonl | jq .
# Filtrar registros donde role es "ingeniera"
cat data.jsonl | jq 'select(.role == "ingeniera")'
# Extraer solo el campo name
cat data.jsonl | jq -r '.name'
# Buscar líneas que contengan una palabra clave
grep '"Alicia"' data.jsonlCómo convertir JSON a JSONL
Si tienes un array JSON estándar, para convertirlo a JSONL basta con escribir cada elemento en una línea independiente. Esta es una de las operaciones más habituales con JSONL.
import json
# Leer arreglo JSON
with open("data.json", "r", encoding="utf-8") as f:
data = json.load(f) # espera un arreglo JSON
# Escribir como 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"Convertidos {len(data)} registros de JSON a JSONL")import { readFileSync, writeFileSync } from 'fs';
// Leer arreglo JSON
const data = JSON.parse(readFileSync('data.json', 'utf-8'));
// Escribir como JSONL
const jsonl = data
.map(record => JSON.stringify(record))
.join('\n');
writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Convertidos ${data.length} registros de JSON a JSONL`);Cómo convertir CSV a JSONL
Al convertir CSV a JSONL, cada fila se transforma en un objeto JSON cuyos nombres de campo se toman de la cabecera del CSV. Esto resulta útil para migrar datos tabulares a un formato adecuado para el procesamiento en streaming o el aprendizaje automático.
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("CSV convertido a JSONL exitosamente")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('CSV convertido a JSONL exitosamente');Buenas prácticas con JSONL
Usa la codificación UTF-8 en todos los archivos JSONL. Así garantizas la compatibilidad entre plataformas y puedes utilizar caracteres de distintos idiomas.
Escribe exactamente un objeto JSON por línea. Nunca dividas un objeto JSON en varias líneas ni coloques varios objetos en la misma línea.
No añadas comas entre las líneas. A diferencia de los arrays JSON, JSONL utiliza los caracteres de salto de línea como único delimitador.
Valida cada línea por separado. Cada una debe contener un valor JSON completo y válido. Usa un validador de JSONL para detectar los errores de sintaxis cuanto antes.
Lee los archivos grandes en streaming. En lugar de cargar todo el archivo en memoria, procésalo línea por línea con readline (Node.js) o recorriendo las líneas del archivo (Python).
Mantén una estructura coherente en todos los registros. Aunque JSONL permite utilizar un esquema distinto en cada línea, una estructura uniforme facilita mucho el procesamiento de los datos.
Evita los espacios en blanco al final de las líneas. Comprueba que no haya espacios ni tabulaciones de más que puedan causar problemas al parsear los datos.
Termina el archivo con un salto de línea. Añadir un salto de línea después del último registro ayuda a que herramientas como wc y cat procesen el archivo correctamente.
Errores comunes en JSONL
[
{"name":"Alicia"},
{"name":"Roberto"}
]{"name":"Alicia"}
{"name":"Roberto"}JSONL no es un array JSON. No encierres las líneas entre corchetes ni añadas comas entre ellas. Cada línea es independiente.
{"name":"Alicia"},
{"name":"Roberto"},{"name":"Alicia"}
{"name":"Roberto"}En JSONL no se permiten comas al final de cada línea ni entre las líneas. El carácter de salto de línea es el único separador.
{
"name": "Alicia",
"age": 30
}{"name":"Alicia","age":30}Cada objeto JSON debe ocupar una sola línea. El JSON formateado con sangría y saltos de línea para facilitar su lectura no es JSONL válido.
{"text":"Ella dijo "hola""}{"text":"Ella dijo \"hola\""}Las comillas y los caracteres especiales dentro de las cadenas JSON deben escaparse correctamente con barras invertidas. Las comillas sin escapar provocan errores en el parser de JSON.
Valida tu archivo JSONL
Después de crear tu archivo JSONL, valídalo para detectar los errores de sintaxis cuanto antes. Nuestro validador gratuito comprueba cada línea al instante.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Da formato a los archivos JSONL con una sangría adecuada para facilitar su lectura, depuración y revisión.
Convierte arrays JSON al formato JSONL. Ideal para preparar datos para streaming y entrenamiento de modelos de ML.
Exporta datos JSONL a hojas de cálculo CSV para analizarlos en Excel o Google Sheets.
Guía completa para trabajar con archivos JSONL en Python. Aprende a leer, escribir y parsear JSONL con json, pandas y orjson, y a usar streaming para archivos grandes.