JSONL vs NDJSON: ¿cuál es la diferencia?
Una guía completa para comparar JSONL (JSON Lines) y NDJSON (Newline Delimited JSON): dos nombres para un formato casi idéntico, con algunos matices que conviene conocer.
Comparación rápida: JSONL vs NDJSON
| Característica | JSONL (JSON Lines) | NDJSON |
|---|---|---|
| Nombre completo | JSON Lines | Newline Delimited JSON |
| Extensión de archivo | .jsonl | .ndjson |
| Especificación | jsonlines.org (informal) | github.com/ndjson/ndjson-spec (especificación informal) |
| Origen | Convención de la comunidad, popularizada por las herramientas de ciencia de datos | Propuesta por Chris Olah, Thorsten Ball y otros |
| Separador de líneas | \n (salto de línea) | \n (salto de línea) |
| Tipo MIME | application/jsonl (no oficial) | application/x-ndjson |
| Compatibilidad con streaming | Sí, línea por línea | Sí, línea por línea |
| Adopción | OpenAI, Hugging Face, ecosistema de IA/ML | Elasticsearch, Apache Spark, ingeniería de datos |
¿Qué es JSONL (JSON Lines)?
JSONL, abreviatura de JSON Lines, es un formato de datos de texto en el que cada línea contiene un único valor JSON válido. Las líneas se separan con caracteres de salto de línea (\n). Las comunidades de aprendizaje automático y ciencia de datos popularizaron este formato, cuya definición informal se encuentra en jsonlines.org.
Los archivos JSONL usan la extensión .jsonl. El formato se ha convertido en el estándar para los datos de entrenamiento de IA y ML: OpenAI exige archivos .jsonl para el fine-tuning, y los datasets de Hugging Face suelen usar el formato JSON Lines.
{"id": 1, "text": "Hola mundo", "label": "saludo"}
{"id": 2, "text": "¿Cómo estás?", "label": "pregunta"}
{"id": 3, "text": "Adiós", "label": "despedida"}¿Qué es NDJSON (Newline Delimited JSON)?
NDJSON, o Newline Delimited JSON, es un formato de datos en el que cada línea contiene un valor JSON válido y las líneas se separan con caracteres de salto de línea. Su especificación se aloja en github.com/ndjson/ndjson-spec y se formalizó para ofrecer un estándar más estructurado para los datos JSON delimitados por saltos de línea.
Los archivos NDJSON usan la extensión .ndjson y tienen como tipo MIME registrado application/x-ndjson. El formato se usa ampliamente en ingeniería de datos, procesamiento de logs y aplicaciones de streaming. Elasticsearch, Apache Spark y muchas streaming APIs sobre HTTP usan NDJSON.
{"id": 1, "text": "Hola mundo", "label": "saludo"}
{"id": 2, "text": "¿Cómo estás?", "label": "pregunta"}
{"id": 3, "text": "Adiós", "label": "despedida"}¿JSONL y NDJSON son el mismo formato?
En la práctica, sí: JSONL y NDJSON son funcionalmente idénticos. Ambos almacenan un valor JSON por línea y separan las líneas con caracteres de salto de línea (\n). Un archivo .jsonl y otro .ndjson que contengan los mismos datos son completamente intercambiables: cualquier herramienta que lea uno de los formatos puede leer el otro.
Las diferencias se limitan al nombre, las comunidades que los usan y las convenciones de metadatos. JSONL (JSON Lines) surgió de la comunidad de ciencia de datos y aprendizaje automático, mientras que la comunidad de ingeniería de datos y streaming web formalizó NDJSON (Newline Delimited JSON). Piensa en «película» y «film»: se refieren a lo mismo, pero cada ámbito tiene sus preferencias al nombrarlo.
Las diferencias más relevantes son la extensión del archivo (.jsonl vs .ndjson) y el tipo MIME. NDJSON tiene un tipo MIME más reconocido (application/x-ndjson), que se usa para streaming sobre HTTP, mientras que los archivos JSONL son el estándar en los flujos de trabajo de IA/ML. Para elegir entre ambos, sigue la convención de tu ecosistema.
Diferencias clave entre JSONL y NDJSON
1. Especificación y referencia
Se define en jsonlines.org mediante una especificación breve e informal. Las reglas son sencillas: cada línea contiene un valor JSON válido, las líneas se separan con '\n' y se recomienda usar la codificación UTF-8.
Se define en github.com/ndjson/ndjson-spec mediante una especificación algo más formal. NDJSON exige explícitamente que cada línea contenga un valor JSON válido y que el separador sea '\n' (no '\r\n'). También recomienda incluir un salto de línea al final.
2. Extensión de archivo
Usa la extensión .jsonl, el estándar para los archivos de fine-tuning de OpenAI, los datasets de Hugging Face y la mayoría de las herramientas de ML/IA. GitHub y VS Code reconocen los archivos .jsonl y ofrecen resaltado de sintaxis.
Usa la extensión .ndjson, habitual en las herramientas de ingeniería de datos, las APIs de operaciones en bloque de Elasticsearch y las respuestas HTTP en streaming. Muchos editores también ofrecen resaltado de sintaxis para .ndjson.
3. Tipo MIME
No tiene un tipo MIME registrado oficialmente. Entre los tipos no oficiales más habituales están application/jsonl y application/json-lines. En la práctica, muchos sistemas usan application/jsonl o recurren a application/json.
Usa el tipo MIME application/x-ndjson, más reconocido en el contexto de HTTP. Lo utilizan Elasticsearch, el estándar de streaming de la API Fetch y varios frameworks web para las respuestas en streaming.
4. Uso en la comunidad y el ecosistema
Es el formato predominante en el ecosistema de IA/ML. OpenAI, Anthropic, Google Gemini, Hugging Face y la mayoría de los frameworks de ML usan .jsonl. En el conjunto de la comunidad de desarrolladores, el término 'JSONL' es más conocido y se busca con más frecuencia.
Es la opción preferida en ingeniería de datos y sistemas backend. Elasticsearch, Apache Spark, PostgreSQL COPY y muchas herramientas de agregación de logs usan NDJSON. El paquete ndjson de npm acumula millones de descargas semanales.
Cuándo usar JSONL y cuándo NDJSON
- Prepares datos de entrenamiento para OpenAI, Anthropic o el fine-tuning de otros LLM
- Trabajes con datasets de Hugging Face
- Crees pipelines de ML y procesos de preprocesamiento de datos
- Tu equipo o tu documentación use el término 'JSON Lines'
- Subas archivos a plataformas de IA/ML que requieran la extensión .jsonl
- Trabajes en entornos de ciencia de datos con Python
- Transmitas datos JSON en streaming sobre HTTP (Server-Sent Events, fetch streaming)
- Trabajes con la API de operaciones en bloque de Elasticsearch
- Crees pipelines de datos con Apache Spark o herramientas similares
- Configures cabeceras Content-Type (application/x-ndjson)
- Tu infraestructura o tu equipo siga la convención NDJSON
- Trabajes con bibliotecas de streaming de Node.js
Ejemplos de código: cómo leer JSONL y NDJSON
# Leer JSONL - exactamente igual que leer NDJSON
import json
with open('data.jsonl', 'r') as f:
for line in f:
record = json.loads(line.strip())
print(record['text'])
# Salida:
# Hola mundo
# ¿Cómo estás?
# Adiós// Leer NDJSON - exactamente igual que leer 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);
}
// Salida:
// Hola mundo
// ¿Cómo estás?
// AdiósValida tus archivos JSONL / NDJSON
Comprueba si tu archivo .jsonl o .ndjson tiene el formato correcto. Nuestro validador gratuito comprueba que cada línea tenga una sintaxis JSON válida.
Todo sobre NDJSON: especificación, tipo MIME, lectura y escritura en Python y Node.js, APIs HTTP en streaming, herramientas del ecosistema y su relación con JSONL.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Descubre qué es JSONL (JSON Lines), en qué se diferencia del JSON convencional y por qué es el formato preferido para datos en streaming, archivos de logs y datasets de aprendizaje automático.
Aprende a transmitir datos JSONL en tiempo real con Node.js, Python, Server-Sent Events y WebSockets. Crea pipelines de streaming para logs, métricas y flujos de datos en directo.
Una comparación detallada entre JSON y JSONL. Aprende cuándo usar cada formato, cuáles son sus ventajas e inconvenientes y cómo convertir de uno a otro.