JSONL na prática: abrir, converter e depurar linhas defeituosas

Em resumo: cada linha de um arquivo JSONL é um valor JSON válido e independente, mas o arquivo como um todo não é um único documento JSON. Se entregar o arquivo completo ao JSON.parse ou json.load falha, em nove de cada dez vezes o arquivo está bem — sua estratégia de leitura é que está errada.

Um registro por linha, sem vírgulas entre as linhas, sem array externo — o JSONL abre mão da "estrutura do documento inteiro" para ganhar escrita por acréscimo, leitura em streaming e isolamento de falhas linha a linha. Os três benefícios só se materializam quando você processa o arquivo linha por linha, e os três viram erros no momento em que você tenta analisar tudo de uma vez.

1. Três nomes, um formato: JSONL, NDJSON, JSON Lines

Iniciantes costumam assumir que a diferença de nomes implica diferença de sintaxe. Não implica:

Qualquer ferramenta que lê um formato lê o outro. O único critério para escolher o nome é a convenção do seu ecossistema a jusante: escreva .jsonl ao preparar datasets para o Hugging Face, declare application/x-ndjson ao expor uma API em streaming. Um arquivo JSONL portável satisfaz três regras: codificação UTF-8 (sem BOM), um valor JSON completo por linha, linhas separadas por \n. Uma quebra de linha final no fim do arquivo é fortemente recomendada, e linhas em branco não são registros válidos. Os detalhes do protocolo e a motivação do design ficam cobertos no nosso panorama de JSON Lines e NDJSON; este artigo trata estritamente do que fazer quando o arquivo já está em mãos.

2. Inspeção: primeiro head, depois grep, e só então um editor

Dar um duplo clique num .jsonl de 500 MB para abrir no editor é o erro mais comum: três milhões de linhas mais destaque de sintaxe mais buffer de desfazer vão congelar praticamente qualquer editor — e a culpa não é do JSON. Analisar um documento de 45 MB leva cerca de 208 ms no Node 22; o que trava é a renderização. Formatos orientados a linha existem para ferramentas de linha, porque os registros coincidem com as linhas físicas:

复制# Primeiro meça a escala: contagem de registros e tamanho do arquivo, sem ler o conteúdo
wc -l events.jsonl && du -h events.jsonl

# Veja como é um registro (confirme campos e estrutura)
head -n 1 events.jsonl | jq .

# Encontre registros-alvo diretamente: ferramentas de linha simplesmente funcionam — um privilégio do JSONL
grep '"level":"error"' events.jsonl | head -n 5
tail -n 100 events.jsonl | jq 'select(.latency_ms > 500)'

Repare no último comando: cada linha que sai do tail ainda é um valor JSON independente, logo pode ir direto para o jq, sem precisar reconstruir um array. Essa abordagem funciona igual em arquivos de vários gigabytes com sobrecarga de memória quase nula — é o mesmo princípio de por que arquivos JSON grandes deixam as páginas lentas.

3. Os três padrões padrão de leitura linha a linha

A leitura linha a linha precisa lidar com três coisas: pular linhas em branco (especialmente a quebra final), reportar erros com número de linha e nunca deixar uma única linha defeituosa derrubar o trabalho inteiro. Os padrões padrão das três linguagens giram em torno desses pontos.

Python, apenas biblioteca padrão:

复制import json

with open("events.jsonl", encoding="utf-8") as f:
    for line_number, line in enumerate(f, start=1):
        if not line.strip():          # pular linhas em branco
            continue
        try:
            record = json.loads(line) # analisar cada linha independentemente
        except json.JSONDecodeError as e:
            print(f"Linha {line_number} falhou: {e}")  # reportar, não abortar
            continue                  # isolar a linha defeituosa
        handle(record)

Node com o módulo readline embutido, memória constante independente do tamanho do arquivo:

复制import fs from "node:fs";
import readline from "node:readline";

const input = fs.createReadStream("events.jsonl", "utf8");
const lines = readline.createInterface({ input, crlfDelay: Infinity });
let lineNumber = 0;
for await (const line of lines) {
  lineNumber += 1;
  if (!line.trim()) continue;
  try {
    handle(JSON.parse(line));
  } catch (e) {
    console.error(`Linha ${lineNumber}: ${e.message}`);
  }
}

No Go 1.27, encoding/json/v2 se torna padrão estável, e seu decodificador em fluxo valor a valor se encaixa perfeitamente no JSONL; use gojq se precisar embutir expressões jq. Quanto às bibliotecas, não corra para instalar pacotes: jsonlines em Python reporta o número e o texto bruto de qualquer linha com falha, e orjsonl lê e grava diretamente arquivos comprimidos com gzip/bzip2/zstd; o pacote Node ndjson não publica versões desde 2020 — o readline embutido basta.

4. Convertendo de e para arrays JSON

O sentido importa; inverta-o e todos os comandos sairão errados. Lembre uma regra: array → JSONL é um map (cada registro compactado em uma linha), JSONL → array é um collect (linhas reunidas em uma lista).

复制# Array JSON → JSONL: -c compacta cada elemento em uma linha
jq -c '.[]' records.json > records.jsonl

# JSONL → array JSON: -s reúne toda a entrada em um único array
jq -s '.' events.jsonl > records.json

# Filtrar JSONL linha a linha: não precisa de -s, o jq processa a entrada como fluxo
jq -c 'select(.active == true)' events.jsonl > active.jsonl

Os one-liners de Python são equivalentes: array → JSONL grava json.dumps(r, ensure_ascii=False) + "\n" por registro; o inverso coleta os json.loads linha a linha numa lista. Cada sentido tem sua armadilha. Na ida (array → JSONL), toda quebra de linha real dentro de um registro precisa estar escapada pelo json.dumps — senão um registro se rasga em várias linhas. Na volta (JSONL → array), não concatene as linhas numa única string gigante para analisar — com milhões de linhas é uma cópia integral desnecessária na memória. Agregações (somas, agrupamentos, médias) exigem -s, que carrega tudo; em arquivos de vários GB, troque para awk ou um acumulador em streaming em Python.

5. Seis tipos de linhas defeituosas e como diagnosticá-las

Praticamente todo erro de JSONL mora no nível da linha. Validar linha a linha reportando números de linha é o único diagnóstico confiável. Ordenadas por frequência:

A rotina de diagnóstico é sempre de três passos: head -n 1 para confirmar codificação e estrutura da primeira linha; rodar um script linha a linha que reporta o número de todas as linhas defeituosas em vez de parar na primeira; depois copiar as linhas defeituosas para fora, uma a uma — uma linha é um registro completo, inspecioná-la isoladamente não custa nada. Para importações em lote, a política recomendada é "quarentena, não aborto": escreva as linhas defeituosas com seus números em errors.jsonl, siga carregando as boas, e decida sobre reimportar com base na proporção de linhas defeituosas.

6. JSONL sobre HTTP: consumo linha a linha e backpressure

O padrão típico de NDJSON sobre HTTP é um servidor escrevendo continuamente e um cliente consumindo continuamente. No cliente, não chame response.json() — ele bufferiza o corpo inteiro antes de analisar, o que anula o sentido do streaming. Leia o stream do corpo diretamente, divida em \n e carregue qualquer fragmento final incompleto para a próxima iteração:

复制const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const lines = buffer.split("\n");
  buffer = lines.pop();               // o último pedaço pode ser uma linha incompleta
  for (const line of lines) {
    if (line.trim()) handle(JSON.parse(line));
  }
}

No servidor, duas coisas são obrigatórias: primeiro, quando res.write() devolver false, aguarde o evento drain (backpressure), senão a memória cresce sem limite sempre que o consumidor for mais lento que o produtor; segundo, desative o middleware gzip nas rotas de streaming — o gzip precisa bufferizar a resposta inteira antes de comprimir qualquer coisa, o que neutraliza completamente o streaming NDJSON. Ambos os comportamentos foram confirmados por testes locais e várias fontes independentes em inglês, não são suposições.

7. Quando o JSONL é a escolha errada

O espaço negativo da escolha de formato também importa. Três cenários devem ficar com o array JSON:

Regra de bolso em uma frase: se os registros chegam com o tempo ou são consumidos linha por linha (logs, eventos, exportações, conjuntos de treinamento), use JSONL; se um volume pequeno é produzido uma vez, consumido uma vez e precisa da semântica de documento inteiro, use um array JSON. Variantes derivadas (JSON Text Sequences delimitadas por RS) são outro assunto — veja o artigo sobre RFC 7464.

FAQ

Existe alguma diferença real entre JSONL e NDJSON?

Em termos de engenharia, não. Ambos significam "um valor JSON completo por linha, sem wrapper externo, sem vírgulas entre as linhas", e qualquer ferramenta que suporta um suporta o outro. A diferença é de nomenclatura e hábitos do ecossistema: .jsonl domina a engenharia de dados e datasets de ML; .ndjson e application/x-ndjson dominam as APIs HTTP em streaming. Ao integrar com um sistema externo, siga a extensão e o media type que a documentação dele especifica.

Posso ler um arquivo .jsonl diretamente com JSON.parse?

Não o arquivo todo. O JSON.parse aceita exatamente um texto JSON, enquanto o JSONL é uma série de valores independentes dispostos linha por linha, então a análise do arquivo inteiro sempre falha com "Unexpected token" ou "Extra data". Divida em linhas e analise cada linha não vazia separadamente, reportando o número da linha em caso de falha.

Se uma linha de um arquivo JSONL está corrompida, o arquivo inteiro está perdido?

Não — o isolamento de falhas linha a linha é o núcleo do design do formato. Uma linha ruim afeta só a si mesma: pule-a, registre seu número e continue a leitura. Para importações em lote, coloque as linhas defeituosas em quarentena num arquivo separado, carregue os registros corretos normalmente e decida sobre corrigir e reimportar com base na proporção de linhas defeituosas.

Como converter JSONL para Excel ou CSV?

Primeiro transforme em array ou extraia os campos linha a linha, depois rode uma conversão tabular: compacte com jq -c '.[]' data.jsonl e entregue a um conversor, ou passe cada linha pelo json.loads direto ao pandas. Atenção: campos aninhados achatados produzem nomes de colunas com pontos, campos array só podem ser serializados como texto dentro da célula, e colunas de IDs longos devem ser declaradas como string desde o início para evitar perda de precisão.