Guia completo de NDJSON: entenda o JSON delimitado por quebras de linha
Um guia completo sobre Newline Delimited JSON (NDJSON). Conheça a especificação e o tipo MIME, aprenda a ler e escrever NDJSON em Python, Node.js e na linha de comando, veja como usá-lo em APIs HTTP de streaming e entenda sua relação com JSONL.
O que é NDJSON?
NDJSON significa Newline Delimited JSON. É um formato de dados em texto no qual cada linha contém exatamente um valor JSON válido, com as linhas separadas por um caractere de quebra de linha (\n). O formato foi criado para fazer streaming e processar grandes conjuntos de dados sem carregar o arquivo inteiro na memória. Enquanto um arquivo JSON padrão reúne tudo em um único array ou objeto, o NDJSON permite ler, escrever e processar um registro por vez.
A especificação do NDJSON está em github.com/ndjson/ndjson-spec. Ela foi criada para formalizar uma prática que já era comum no envio de logs, em pipelines de dados e em APIs HTTP de streaming. Cada linha é independente: se uma delas contiver JSON inválido, as demais ainda poderão ser interpretadas normalmente. Isso torna o NDJSON tolerante a falhas e adequado a fluxos de trabalho em que os dados são apenas acrescentados ao final, como logs de aplicações, streams de eventos e exportações incrementais de dados.
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}A especificação do NDJSON
A especificação oficial do NDJSON, disponível em github.com/ndjson/ndjson-spec, é intencionalmente enxuta. Ela define uma convenção simples para serializar vários valores JSON em um único stream de texto. As regras básicas são simples:
A especificação evita explicitamente a inclusão de cabeçalhos, metadados ou informações de schema no formato. Assim, o NDJSON permanece o mais simples possível e compatível com as ferramentas padrão de processamento de texto do Unix. Cada linha pode conter qualquer valor JSON válido, embora, na prática, a maioria dos arquivos NDJSON contenha objetos JSON com um conjunto consistente de chaves.
- Cada linha DEVE conter exatamente um valor JSON válido (objeto, array, string, número, booleano ou null).
- As linhas são separadas pelo caractere de quebra de linha '\n' (U+000A). O caractere de retorno de carro '\r' (U+000D) pode aparecer antes de '\n', mas não é obrigatório.
- É permitido, mas não obrigatório, incluir uma quebra de linha após o último valor JSON.
- Nenhum valor JSON pode conter caracteres de quebra de linha sem escape em seu conteúdo.
Como há poucas regras, é fácil gerar NDJSON em qualquer linguagem de programação que tenha um serializador JSON. Basta serializar cada registro, acrescentar uma quebra de linha e gravá-lo na saída. Não é preciso se preocupar com colchetes de fechamento, vírgulas no final ou um array que englobe todos os registros.
NDJSON vs JSON vs JSONL
NDJSON, JSON e JSONL têm diferenças de estrutura. O JSON padrão codifica um único valor (geralmente um array ou objeto). Já JSONL e NDJSON armazenam um valor JSON por linha e são funcionalmente idênticos. A tabela abaixo destaca as principais diferenças entre os três formatos.
| Característica | JSON | JSONL | NDJSON |
|---|---|---|---|
| Nome completo | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| Extensão do arquivo | .json | .jsonl | .ndjson |
| Tipo MIME | application/json | application/jsonl (nao oficial) | application/x-ndjson |
| Especificação | RFC 8259 (padrão IETF) | jsonlines.org (comunidade) | github.com/ndjson/ndjson-spec (comunidade) |
| Delimitador de linha | N/A (valor único) | \n (nova linha) | \n (nova linha) |
| Quebra de linha no final | N/A | Recomendada | Opcional |
| Suporte a streaming | Não (é preciso interpretar o documento inteiro) | Sim (linha por linha) | Sim (linha por linha) |
Tipo MIME do NDJSON: application/x-ndjson
O tipo MIME registrado para NDJSON é application/x-ndjson. Ele é usado nos cabeçalhos HTTP para indicar que o corpo da resposta contém dados JSON delimitados por quebras de linha. Muitas APIs de streaming, como a API do GitHub, a API do Docker Registry e a API bulk do Elasticsearch, usam esse tipo MIME para enviar 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 também aceitam application/json-seq (RFC 7464) ou text/plain como alternativas. No entanto, application/x-ndjson é o tipo MIME mais adotado para streams de JSON delimitado por quebras de linha. Ao criar uma API que transmita registros JSON em streaming, use application/x-ndjson para garantir a maior compatibilidade possível.
Leitura e escrita de NDJSON
Trabalhar com NDJSON é simples em qualquer linguagem com suporte a JSON. Veja a seguir exemplos práticos em Python, Node.js e na linha de comando.
O módulo json da biblioteca padrão do Python permite trabalhar com NDJSON de forma simples. Leia o arquivo linha por linha, interprete cada linha com json.loads e use json.dumps para escrever os dados. Para arquivos grandes, essa abordagem linha por linha mantém o uso de memória 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')No Node.js, use o módulo readline com fs.createReadStream para interpretar arquivos NDJSON com eficiência. O stream processa uma linha por vez e mantém baixo o consumo de memória, independentemente do tamanho do arquivo.
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');A ferramenta de linha de comando jq aceita NDJSON como entrada nativamente. Use a opção --slurp para reunir todos os registros em um array ou processe cada registro individualmente, sem precisar de nenhuma opção.
# 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 em APIs HTTP de streaming
O NDJSON é o padrão de fato para APIs HTTP de streaming que fornecem dados em tempo real. Quando um servidor envia uma resposta NDJSON, o cliente pode começar a processar o primeiro registro assim que ele chega, sem esperar o fim da resposta. Isso é mais rápido e consome menos memória do que retornar um grande array JSON.
Entre os serviços populares que usam streaming de NDJSON estão Docker Registry (eventos de camadas de imagens), Elasticsearch (operações em massa), Apache CouchDB (feed de alterações) e muitas APIs modernas orientadas a eventos. Essa abordagem funciona bem em alternativas a Server-Sent Events, no acompanhamento de logs em tempo real e no carregamento progressivo de dados em aplicações 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);
}Ferramentas do ecossistema NDJSON
Um número crescente de ferramentas de linha de comando e bibliotecas oferece suporte nativo a NDJSON. Com elas, você pode filtrar, transformar e analisar dados NDJSON sem escrever código específico para isso.
jq
EssencialO jq é o processador de JSON mais popular na linha de comando. Ele lê NDJSON por padrão (um valor JSON por linha) e permite filtrar, mapear, agrupar e reformatar os dados. Use jq -c para gerar uma saída compacta e jq -s para reunir todos os registros em um array.
ndjson-cli
CLIO ndjson-cli é uma coleção de comandos no estilo Unix para manipular streams de NDJSON: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort e ndjson-join. Cada comando lê de stdin e escreve em stdout, o que permite combiná-los por meio de pipes.
ndjson (npm)
Node.jsO pacote ndjson do npm oferece parsers e serializadores de NDJSON em streaming para Node.js. Ele disponibiliza os streams de transformação ndjson.parse() e ndjson.stringify(), que se integram diretamente aos pipelines de streams do Node.js para processar grandes volumes de dados com alta vazão.
NDJSON e JSONL: interoperabilidade
NDJSON e JSONL (JSON Lines) são formatos funcionalmente idênticos. Ambos armazenam um valor JSON por linha, com as linhas separadas por caracteres de quebra de linha. Um arquivo NDJSON válido também é um JSONL válido, e vice-versa. Você pode renomear um arquivo .ndjson para .jsonl (ou o contrário) sem alterar um único byte do conteúdo, e qualquer ferramenta que leia um dos formatos também lerá o outro.
As únicas diferenças são de apresentação: o NDJSON vem de github.com/ndjson/ndjson-spec e usa a extensão .ndjson com o tipo MIME application/x-ndjson, enquanto o JSONL vem de jsonlines.org e usa a extensão .jsonl. Na prática, a maioria dos desenvolvedores trata os dois nomes como sinônimos. Se o seu projeto já usa JSONL, não há necessidade de migrar para NDJSON. Da mesma forma, uma biblioteca com suporte a NDJSON funciona com seus arquivos .jsonl sem nenhuma alteração.
Experimente nossas ferramentas gratuitas para NDJSON/JSONL
Trabalhe com arquivos NDJSON e JSONL diretamente no seu navegador. Todo o processamento é feito localmente, mantendo seus dados privados.
Entenda a relação entre JSONL e NDJSON (Newline Delimited JSON). Conheça as diferenças sutis e saiba quando usar cada termo.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Aprenda a transmitir dados JSONL em tempo real usando Node.js, Python, Server-Sent Events e WebSockets. Crie pipelines de streaming para logs, métricas e feeds de dados em tempo real.
Entenda o que é JSONL (JSON Lines), como ele se diferencia do JSON convencional e por que é o formato preferido para streaming de dados, arquivos de log e datasets de aprendizado de máquina.
Converta arquivos JSONL em um array JSON padrão. Ideal para APIs e pipelines de processamento de dados.