Por Jerry Fan

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.

example.jsonl
{"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.

Python
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")
JavaScript / Node.js
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.

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  # saltar líneas vacías
        record = json.loads(line)
        print(f"Línea {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; // saltar líneas vacías
  lineNumber++;
  const record = JSON.parse(line);
  console.log(`Línea ${lineNumber}: ${record.name} - ${record.role}`);
}
Línea de comandos (grep / jq)
# 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.jsonl

Có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.

Python
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")
JavaScript / Node.js
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`);

Convierte a JSONL en línea

¿No quieres escribir código? Usa nuestro conversor gratuito de JSON a JSONL en línea: pega el contenido o sube tu archivo y conviértelo al instante.

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.

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("CSV convertido a JSONL exitosamente")
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('CSV convertido a JSONL exitosamente');

Convierte CSV en línea

Convierte archivos CSV a JSONL al instante con nuestra herramienta gratuita en línea, sin necesidad de escribir código.

Buenas prácticas con JSONL

1

Usa la codificación UTF-8 en todos los archivos JSONL. Así garantizas la compatibilidad entre plataformas y puedes utilizar caracteres de distintos idiomas.

2

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.

3

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.

4

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.

5

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).

6

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.

7

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.

8

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

Agrupar los registros en un array
Incorrecto
[
  {"name":"Alicia"},
  {"name":"Roberto"}
]
Correcto
{"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.

Comas entre líneas
Incorrecto
{"name":"Alicia"},
{"name":"Roberto"},
Correcto
{"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.

Objetos JSON repartidos en varias líneas
Incorrecto
{
  "name": "Alicia",
  "age": 30
}
Correcto
{"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.

Caracteres especiales sin escapar
Incorrecto
{"text":"Ella dijo "hola""}
Correcto
{"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.

Prueba nuestras herramientas gratuitas para JSONL

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. No necesitas subirlos a ningún servidor: todo es 100% privado.

Preguntas frecuentes

Referencias