Por Jerry Fan

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ísticaJSONL (JSON Lines)NDJSON
Nombre completoJSON LinesNewline Delimited JSON
Extensión de archivo.jsonl.ndjson
Especificaciónjsonlines.org (informal)github.com/ndjson/ndjson-spec (especificación informal)
OrigenConvención de la comunidad, popularizada por las herramientas de ciencia de datosPropuesta por Chris Olah, Thorsten Ball y otros
Separador de líneas\n (salto de línea)\n (salto de línea)
Tipo MIMEapplication/jsonl (no oficial)application/x-ndjson
Compatibilidad con streamingSí, línea por líneaSí, línea por línea
AdopciónOpenAI, Hugging Face, ecosistema de IA/MLElasticsearch, 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.

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

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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

JSONLUsa .jsonl cuando:
  • 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
NDJSONUsa .ndjson cuando:
  • 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

Cómo leer un archivo .jsonl (Python)
# 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
Cómo leer un archivo .ndjson (JavaScript/Node.js)
// 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ós

Visualiza archivos JSONL y NDJSON al instante

Abre archivos .jsonl y .ndjson de hasta 1GB en tu navegador. Sin subir archivos ni registrarte: funciona con ambos formatos sin complicaciones.

Preguntas frecuentes

Referencias