Guia Completa de NDJSON: JSON Delimitado por Nueva Linea Explicado

La Especificacion NDJSON

La especificacion oficial de NDJSON en github.com/ndjson/ndjson-spec es intencionalmente minima. Define una convencion simple para serializar multiples valores JSON en un unico flujo de texto. Las reglas principales son directas:

La especificacion evita explicitamente agregar cabeceras, metadatos o informacion de esquema al formato. Esto mantiene NDJSON lo mas simple posible y compatible con herramientas estandar de procesamiento de texto Unix. Cualquier valor JSON valido esta permitido en cada linea, aunque en la practica la mayoria de los archivos NDJSON contienen objetos JSON con un conjunto consistente de claves.

• Cada linea DEBE contener exactamente un valor JSON valido (objeto, array, cadena, numero, booleano o null).
• Las lineas se separan por el caracter de nueva linea '\n' (U+000A). El retorno de carro '\r' (U+000D) puede aparecer antes de '\n' pero no es requerido.
• Se permite una nueva linea final despues del ultimo valor JSON pero no es obligatoria.
• Cada valor JSON no debe contener caracteres de nueva linea sin escapar dentro del propio valor.

Dado que las reglas son minimas, NDJSON es facil de generar desde cualquier lenguaje de programacion que tenga un serializador JSON. Simplemente serializa cada registro, agrega una nueva linea y escribelo en la salida. Sin corchetes de cierre, sin comas finales, sin estructura de array envolvente de la que preocuparse.

Tipo MIME de NDJSON: application/x-ndjson

El tipo MIME registrado para NDJSON es application/x-ndjson. Este tipo de contenido se usa en cabeceras HTTP para indicar que el cuerpo de la respuesta contiene datos JSON delimitados por nueva linea. Muchas APIs en streaming, incluyendo la API de GitHub, la API del registro Docker y la API bulk de Elasticsearch, usan este tipo MIME para entregar 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 tambien aceptan application/json-seq (RFC 7464) o text/plain como alternativas. Sin embargo, application/x-ndjson es el tipo MIME mas ampliamente adoptado para flujos JSON delimitados por nueva linea. Al construir una nueva API que transmita registros JSON, usa application/x-ndjson para maxima compatibilidad.

NDJSON en APIs HTTP en Streaming

NDJSON es el estandar de facto para APIs HTTP en streaming que entregan datos en tiempo real. Cuando un servidor envia una respuesta NDJSON, el cliente puede empezar a procesar el primer registro tan pronto como llega, sin esperar a que se complete toda la respuesta. Esto es mas rapido y mas eficiente en memoria que devolver un array JSON grande.

Los servicios populares que usan streaming NDJSON incluyen Docker Registry (eventos de capas de imagenes), Elasticsearch (operaciones masivas), Apache CouchDB (feed de cambios) y muchas APIs modernas basadas en eventos. El patron funciona bien con alternativas a Server-Sent Events, tail de logs en tiempo real y 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);
}

NDJSON y JSONL: Interoperabilidad

NDJSON y JSONL (JSON Lines) son formatos funcionalmente identicos. Ambos almacenan un valor JSON por linea, separados por caracteres de nueva linea. Un archivo que es NDJSON valido tambien es JSONL valido, y viceversa. Puedes renombrar un archivo .ndjson a .jsonl (o al reves) sin cambiar un solo byte de contenido, y toda herramienta que lee un formato leera el otro.

Las unicas diferencias son cosmeticas: NDJSON proviene de github.com/ndjson/ndjson-spec y usa la extension .ndjson con el tipo MIME application/x-ndjson, mientras que JSONL proviene de jsonlines.org y usa la extension .jsonl. En la practica, la mayoria de los desarrolladores tratan los dos nombres como sinonimos. Si tu proyecto ya usa JSONL, no hay necesidad de migrar a NDJSON, y si una biblioteca dice que soporta NDJSON, funcionara con tus archivos .jsonl sin ningun cambio.