Por Jerry Fan

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.

Ejemplo de NDJSON (3 registros)
{"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ísticaJSONJSONLNDJSON
Nombre completoJavaScript Object NotationJSON LinesNewline Delimited JSON
Extensión de archivo.json.jsonl.ndjson
Tipo MIMEapplication/jsonapplication/jsonl (no oficial)application/x-ndjson
EspecificaciónRFC 8259 (estándar del IETF)jsonlines.org (comunidad)github.com/ndjson/ndjson-spec (comunidad)
Delimitador de líneaN/A (un único valor)\n (salto de línea)\n (salto de línea)
Salto de línea finalN/ARecomendadoOpcional
Compatible con streamingNo (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.

Cabecera HTTP Content-Type
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.

Python: leer y escribir NDJSON
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.

Node.js: leer y escribir NDJSON
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.

Línea de comandos: procesar NDJSON con jq
# 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.ndjson

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

Servidor de streaming NDJSON con Express.js
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);
Navegador: consumir un stream NDJSON con Fetch
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

Esencial

jq 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

CLI

ndjson-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.js

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

JSONL vs NDJSON: comparación detallada

Si quieres conocer más a fondo la historia, las diferencias entre las especificaciones y la adopción de JSONL y NDJSON en la comunidad, consulta nuestra guía comparativa.

Trabaja con archivos NDJSON en línea

Visualiza, valida y convierte archivos NDJSON y JSONL de hasta 1 GB directamente en tu navegador. Sin subir archivos y con un procesamiento 100% privado.

Preguntas frecuentes

Referencias