Guía completa de NDJSON: JSON delimitado por saltos de línea
Una guía completa sobre Newline Delimited JSON (NDJSON). Conoce su especificación y su tipo MIME, aprende a leer y escribir NDJSON con Python, Node.js y la línea de comandos, descubre cómo usarlo en APIs HTTP en streaming y entiende su relación con JSONL.
¿Qué es NDJSON?
NDJSON son las siglas de Newline Delimited JSON (JSON delimitado por saltos de línea). Es un formato de datos de texto en el que cada línea contiene exactamente un valor JSON válido y se separa de la siguiente mediante un salto de línea (\n). Se diseñó para transmitir datos en streaming y procesar grandes conjuntos de datos sin cargar el archivo completo en memoria. A diferencia de un archivo JSON estándar, que agrupa todo en un único array u objeto, NDJSON permite leer, escribir y procesar los registros de uno en uno.
La especificación de NDJSON está disponible en github.com/ndjson/ndjson-spec. Se creó para formalizar un patrón que ya era habitual en el envío de logs, los pipelines de datos y las APIs HTTP en streaming. Cada línea es independiente: si una contiene JSON no válido, las demás se pueden seguir parseando sin problemas. Esto hace que NDJSON sea tolerante a fallos y resulte adecuado para flujos de trabajo en los que solo se añaden registros, como los logs de aplicaciones, los flujos de eventos y las exportaciones incrementales de datos.
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}La especificación de NDJSON
La especificación oficial de NDJSON, disponible en github.com/ndjson/ndjson-spec, es deliberadamente mínima. Define una convención sencilla para serializar varios valores JSON en un único flujo de texto. Sus reglas básicas son las siguientes:
La especificación excluye expresamente las cabeceras, los metadatos y la información de esquema del formato. Así, NDJSON se mantiene lo más sencillo posible y sigue siendo compatible con las herramientas estándar de Unix para procesar texto. Cada línea admite cualquier valor JSON válido, aunque en la práctica la mayoría de los archivos NDJSON contienen objetos JSON con el mismo conjunto de claves.
- Cada línea DEBE contener exactamente un valor JSON válido (objeto, array, cadena, número, booleano o null).
- Las líneas se separan mediante el carácter de salto de línea '\n' (U+000A). El retorno de carro '\r' (U+000D) puede aparecer antes de '\n', pero no es obligatorio.
- Se permite añadir un salto de línea después del último valor JSON, aunque no es obligatorio.
- Los valores JSON no deben contener saltos de línea sin escapar en su interior.
Con unas reglas tan sencillas, es fácil generar NDJSON desde cualquier lenguaje de programación que disponga de un serializador JSON. Basta con serializar cada registro, añadir un salto de línea y escribirlo en la salida. No hay que preocuparse por corchetes de cierre, comas al final ni un array que lo englobe todo.
NDJSON vs JSON vs JSONL
NDJSON, JSON y JSONL tienen estructuras distintas. JSON estándar codifica un único valor, normalmente un array o un objeto. Tanto JSONL como NDJSON almacenan un valor JSON por línea y son funcionalmente idénticos. La siguiente tabla muestra las principales diferencias entre los tres formatos.
| Característica | JSON | JSONL | NDJSON |
|---|---|---|---|
| Nombre completo | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| Extensión de archivo | .json | .jsonl | .ndjson |
| Tipo MIME | application/json | application/jsonl (no oficial) | application/x-ndjson |
| Especificación | RFC 8259 (estándar del IETF) | jsonlines.org (comunidad) | github.com/ndjson/ndjson-spec (comunidad) |
| Delimitador de línea | N/A (un único valor) | \n (salto de línea) | \n (salto de línea) |
| Salto de línea final | N/A | Recomendado | Opcional |
| Compatible con streaming | No (hay que parsear el documento completo) | Sí (línea a línea) | Sí (línea a línea) |
Tipo MIME de NDJSON: application/x-ndjson
El tipo MIME registrado para NDJSON es application/x-ndjson. Se utiliza en las cabeceras HTTP para indicar que el cuerpo de la respuesta contiene datos JSON delimitados por saltos de línea. Muchas APIs en streaming, como la API de GitHub, la API de Docker Registry y la API bulk de Elasticsearch, usan este tipo MIME para enviar respuestas NDJSON.
Content-Type: application/x-ndjson
# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream
# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');Algunas APIs también aceptan application/json-seq (RFC 7464) o text/plain como alternativas. Sin embargo, application/x-ndjson es el tipo MIME más extendido para los flujos de JSON delimitado por saltos de línea. Si desarrollas una API que transmita registros JSON en streaming, usa application/x-ndjson para ofrecer la máxima compatibilidad.
Leer y escribir NDJSON
Trabajar con NDJSON es sencillo en cualquier lenguaje que admita JSON. Estos ejemplos muestran cómo hacerlo con Python, Node.js y la línea de comandos.
El módulo json de la biblioteca estándar de Python permite trabajar con NDJSON de forma sencilla. Lee el archivo línea a línea, parsea cada línea con json.loads y escribe los datos con json.dumps. Para archivos grandes, este enfoque mantiene un consumo de memoria constante.
import json
# Read NDJSON
records = []
with open('data.ndjson', 'r') as f:
for line in f:
line = line.strip()
if line:
records.append(json.loads(line))
print(f'Loaded {len(records)} records')
# Write NDJSON
output = [
{'id': 1, 'event': 'page_view', 'url': '/home'},
{'id': 2, 'event': 'click', 'url': '/pricing'},
{'id': 3, 'event': 'signup', 'url': '/register'},
]
with open('output.ndjson', 'w') as f:
for record in output:
f.write(json.dumps(record) + '\n')En Node.js, usa el módulo readline junto con fs.createReadStream para parsear archivos NDJSON de forma eficiente. El stream procesa las líneas de una en una y mantiene un consumo de memoria bajo, independientemente del tamaño del archivo.
import { createReadStream, writeFileSync } from 'node:fs';
import { createInterface } from 'node:readline';
// Read NDJSON
async function readNdjson(filePath) {
const records = [];
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
const trimmed = line.trim();
if (trimmed) records.push(JSON.parse(trimmed));
}
return records;
}
// Write NDJSON
const data = [
{ id: 1, event: 'page_view' },
{ id: 2, event: 'click' },
];
const ndjson = data.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync('output.ndjson', ndjson, 'utf-8');La herramienta de línea de comandos jq admite NDJSON de forma nativa. Usa la opción --slurp para reunir todos los registros en un array, o procesa cada registro por separado sin añadir ninguna opción.
# Print each record (jq reads NDJSON by default)
jq '.' data.ndjson
# Filter records where event is "click"
jq 'select(.event == "click")' data.ndjson
# Extract specific fields
jq '{id, url}' data.ndjson
# Count total records
jq -s 'length' data.ndjson
# Convert NDJSON to a JSON array
jq -s '.' data.ndjson > data.json
# Convert a JSON array back to NDJSON
jq -c '.[]' data.json > data.ndjsonNDJSON en APIs HTTP en streaming
NDJSON es el estándar de facto para las APIs HTTP en streaming que envían datos en tiempo real. Cuando un servidor envía una respuesta NDJSON, el cliente puede empezar a procesar el primer registro en cuanto llega, sin esperar a recibir la respuesta completa. Es más rápido y consume menos memoria que devolver un array JSON de gran tamaño.
Entre los servicios más conocidos que usan NDJSON en streaming están Docker Registry (eventos de las capas de imágenes), Elasticsearch (operaciones masivas), Apache CouchDB (feed de cambios) y muchas APIs modernas basadas en eventos. Este patrón encaja bien en alternativas a Server-Sent Events, el seguimiento de logs en tiempo real y la carga progresiva de datos en aplicaciones web.
import express from 'express';
const app = express();
app.get('/api/events/stream', (req, res) => {
res.setHeader('Content-Type', 'application/x-ndjson');
res.setHeader('Transfer-Encoding', 'chunked');
// Simulate streaming events
let id = 0;
const interval = setInterval(() => {
id++;
const event = {
id,
type: 'heartbeat',
timestamp: new Date().toISOString(),
};
res.write(JSON.stringify(event) + '\n');
if (id >= 100) {
clearInterval(interval);
res.end();
}
}, 100);
req.on('close', () => clearInterval(interval));
});
app.listen(3000);async function* readNdjsonStream(url) {
const response = await fetch(url, {
headers: { 'Accept': 'application/x-ndjson' },
});
const reader = response.body
.pipeThrough(new TextDecoderStream())
.getReader();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += value;
const lines = buffer.split('\n');
buffer = lines.pop();
for (const line of lines) {
if (line.trim()) yield JSON.parse(line);
}
}
if (buffer.trim()) yield JSON.parse(buffer);
}
// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
console.log('Received:', event);
}Herramientas del ecosistema NDJSON
Cada vez hay más herramientas de línea de comandos y bibliotecas que admiten NDJSON de forma nativa. Con ellas puedes filtrar, transformar y analizar datos NDJSON sin escribir código a medida.
jq
Esencialjq es el procesador de JSON más popular para la línea de comandos. Lee NDJSON por defecto (un valor JSON por línea) y permite filtrar, mapear, agrupar y cambiar el formato de los datos. Usa jq -c para obtener una salida compacta y jq -s para reunir todos los registros en un array.
ndjson-cli
CLIndjson-cli es un conjunto de comandos al estilo Unix para manipular flujos NDJSON: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort y ndjson-join. Cada comando lee de stdin y escribe en stdout, por lo que puedes encadenarlos mediante pipes.
ndjson (npm)
Node.jsEl paquete ndjson de npm ofrece parsers y serializadores de NDJSON en streaming para Node.js. Proporciona los streams de transformación ndjson.parse() y ndjson.stringify(), que se integran directamente en los pipelines de streams de Node.js para procesar datos con un alto rendimiento.
NDJSON y JSONL: interoperabilidad
NDJSON y JSONL (JSON Lines) son formatos funcionalmente idénticos. Ambos almacenan un valor JSON por línea y usan saltos de línea como separadores. Un archivo NDJSON válido también es JSONL válido, y viceversa. Puedes cambiar la extensión de un archivo de .ndjson a .jsonl (o al revés) sin modificar un solo byte de su contenido: cualquier herramienta que lea uno de los formatos también leerá el otro.
Las únicas diferencias son de nombre y convención: NDJSON procede de github.com/ndjson/ndjson-spec y usa la extensión .ndjson y el tipo MIME application/x-ndjson, mientras que JSONL procede de jsonlines.org y usa la extensión .jsonl. En la práctica, la mayoría de los desarrolladores usa ambos nombres como sinónimos. Si tu proyecto ya usa JSONL, no necesitas migrar a NDJSON. Del mismo modo, si una biblioteca indica que admite NDJSON, funcionará con tus archivos .jsonl sin ningún cambio.
Prueba nuestras herramientas gratuitas de NDJSON/JSONL
Trabaja con archivos NDJSON y JSONL directamente en tu navegador. Todo se procesa de forma local, por lo que tus datos se mantienen privados.
Descubre la relación entre JSONL y NDJSON (Newline Delimited JSON), los matices que los diferencian y cuándo usar cada término.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
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.
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.
Convierte archivos JSONL en un array JSON estándar. Ideal para APIs y pipelines de procesamiento de datos.