Guia Completo NDJSON: JSON Delimitado por Nova Linha Explicado

A Especificacao NDJSON

A especificacao oficial do NDJSON em github.com/ndjson/ndjson-spec e intencionalmente minima. Ela define uma convencao simples para serializar multiplos valores JSON em um unico stream de texto. As regras fundamentais sao diretas:

A especificacao evita explicitamente adicionar cabecalhos, metadados ou informacoes de schema ao formato. Isso mantem o NDJSON o mais simples possivel e compativel com ferramentas padrao de processamento de texto Unix. Qualquer valor JSON valido e permitido em cada linha, embora na pratica a maioria dos arquivos NDJSON contenha objetos JSON com um conjunto consistente de chaves.

• Cada linha DEVE conter exatamente um valor JSON valido (objeto, array, string, numero, booleano ou null).
• As linhas sao separadas pelo caractere de nova linha '\n' (U+000A). O retorno de carro '\r' (U+000D) pode aparecer antes de '\n', mas nao e obrigatorio.
• Uma nova linha final apos o ultimo valor JSON e permitida, mas nao obrigatoria.
• Cada valor JSON nao deve conter caracteres de nova linha nao escapados dentro do proprio valor.

Como as regras sao minimas, NDJSON e facil de gerar a partir de qualquer linguagem de programacao que tenha um serializador JSON. Simplesmente serialize cada registro, adicione uma nova linha e escreva na saida. Sem colchetes de fechamento, sem virgulas finais, sem estrutura de array envolvente para se preocupar.

Tipo MIME NDJSON: application/x-ndjson

O tipo MIME registrado para NDJSON e application/x-ndjson. Esse content type e usado em cabecalhos HTTP para indicar que o corpo da resposta contem dados JSON delimitados por nova linha. Muitas APIs de streaming, incluindo a API do GitHub, API do Docker Registry e API bulk do Elasticsearch, usam esse tipo MIME para entregar respostas 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');

Algumas APIs tambem aceitam application/json-seq (RFC 7464) ou text/plain como alternativas. No entanto, application/x-ndjson e o tipo MIME mais amplamente adotado para streams JSON delimitados por nova linha. Ao construir uma nova API que transmite registros JSON, use application/x-ndjson para maxima compatibilidade.

NDJSON em APIs HTTP de Streaming

NDJSON e o padrao de fato para APIs HTTP de streaming que entregam dados em tempo real. Quando um servidor envia uma resposta NDJSON, o cliente pode comecar a processar o primeiro registro assim que ele chega, sem esperar a resposta inteira ser concluida. Isso e mais rapido e eficiente em memoria do que retornar um grande array JSON.

Servicos populares que usam streaming NDJSON incluem Docker Registry (eventos de camada de imagem), Elasticsearch (operacoes em massa), Apache CouchDB (feed de alteracoes) e muitas APIs modernas orientadas a eventos. O padrao funciona bem com alternativas de Server-Sent Events, tail de logs em tempo real e carregamento progressivo de dados em aplicacoes 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 e JSONL: Interoperabilidade

NDJSON e JSONL (JSON Lines) sao formatos funcionalmente identicos. Ambos armazenam um valor JSON por linha, separado por caracteres de nova linha. Um arquivo que e NDJSON valido tambem e JSONL valido, e vice-versa. Voce pode renomear um arquivo .ndjson para .jsonl (ou ao contrario) sem alterar um unico byte de conteudo, e toda ferramenta que le um formato lera o outro.

As unicas diferencas sao cosmeticas: NDJSON vem de github.com/ndjson/ndjson-spec e usa a extensao .ndjson com o tipo MIME application/x-ndjson, enquanto JSONL vem de jsonlines.org e usa a extensao .jsonl. Na pratica, a maioria dos desenvolvedores trata os dois nomes como sinonimos. Se seu projeto ja usa JSONL, nao ha necessidade de migrar para NDJSON, e se uma biblioteca diz que suporta NDJSON, ela funcionara com seus arquivos .jsonl sem nenhuma alteracao.