JSONL vs NDJSON: Qual é a Diferença?
Um guia completo comparando JSONL (JSON Lines) e NDJSON (Newline Delimited JSON) — dois nomes para praticamente o mesmo formato, com diferenças sutis que vale a pena conhecer.
Última atualização: fevereiro de 2026
Comparação Rápida: JSONL vs NDJSON
| Característica | JSONL (JSON Lines) | NDJSON |
|---|---|---|
| Nome Completo | JSON Lines | Newline Delimited JSON |
| Extensão de Arquivo | .jsonl | .ndjson |
| Especificação | jsonlines.org (informal) | github.com/ndjson/ndjson-spec (especificação informal) |
| Origem | Convenção da comunidade, popularizada por ferramentas de ciência de dados | Proposto por Chris Olah, Thorsten Ball e outros |
| Delimitador de Linha | \n (quebra de linha) | \n (quebra de linha) |
| Tipo MIME | application/jsonl (não oficial) | application/x-ndjson |
| Suporte a Streaming | Sim, linha por linha | Sim, linha por linha |
| Adoção | OpenAI, Hugging Face, ecossistema ML/AI | Elasticsearch, Apache Spark, engenharia de dados |
O que é JSONL (JSON Lines)?
JSONL, abreviação de JSON Lines, é um formato de dados baseado em texto onde cada linha contém um único valor JSON válido. As linhas são separadas por caracteres de quebra de linha (\n). O formato foi popularizado pelas comunidades de aprendizado de máquina e ciência de dados, e é definido informalmente em jsonlines.org.
Arquivos JSONL usam a extensão de arquivo .jsonl. O formato tornou-se o padrão para dados de treinamento de IA e ML — a OpenAI requer arquivos .jsonl para fine-tuning, e datasets do Hugging Face comumente usam o formato JSON Lines.
{"id": 1, "text": "Hello world", "label": "greeting"}{"id": 2, "text": "How are you?", "label": "question"}{"id": 3, "text": "Goodbye", "label": "farewell"}
O que é NDJSON (Newline Delimited JSON)?
NDJSON, ou Newline Delimited JSON, é um formato de dados onde cada linha é um valor JSON válido separado por caracteres de quebra de linha. A especificação está hospedada em github.com/ndjson/ndjson-spec e foi formalizada para fornecer um padrão mais estruturado para dados JSON delimitados por linha.
Arquivos NDJSON usam a extensão de arquivo .ndjson e têm um tipo MIME registrado de application/x-ndjson. O formato é amplamente adotado em engenharia de dados, processamento de logs e aplicações de streaming — Elasticsearch, Apache Spark e muitas APIs HTTP de streaming usam NDJSON.
{"id": 1, "text": "Hello world", "label": "greeting"}{"id": 2, "text": "How are you?", "label": "question"}{"id": 3, "text": "Goodbye", "label": "farewell"}
JSONL e NDJSON São o Mesmo Formato?
Na prática, sim — JSONL e NDJSON são formatos funcionalmente idênticos. Ambos armazenam um valor JSON por linha, separados por caracteres de quebra de linha (\n). Um arquivo .jsonl e um arquivo .ndjson com os mesmos dados são completamente intercambiáveis, e qualquer ferramenta que leia um formato pode ler o outro.
As diferenças são puramente em nomenclatura, adoção da comunidade e convenções de metadados. JSONL (JSON Lines) surgiu da comunidade de ciência de dados e aprendizado de máquina, enquanto NDJSON (Newline Delimited JSON) foi formalizado pela comunidade de engenharia de dados e streaming web. Pense nisso como "filme" vs "cinema" — mesma coisa, diferentes preferências de nome em diferentes círculos.
A diferença mais significativa é a extensão de arquivo (.jsonl vs .ndjson) e o tipo MIME. NDJSON tem um tipo MIME mais amplamente reconhecido (application/x-ndjson) que é usado em contextos de streaming HTTP, enquanto arquivos JSONL são o padrão em fluxos de trabalho de IA/ML. Ao escolher entre eles, siga a convenção do seu ecossistema.
Principais Diferenças Entre JSONL e NDJSON
1. Especificação e Autoridade
Definido em jsonlines.org com uma especificação concisa e informal. A especificação é direta: cada linha é um valor JSON válido, as linhas são separadas por '\n', e a codificação UTF-8 é recomendada.
Definido em github.com/ndjson/ndjson-spec com uma especificação um pouco mais formal. NDJSON explicitamente requer que cada linha seja um valor JSON válido e que o separador de linha seja '\n' (não '\r\n'), com uma quebra de linha final recomendada.
2. Extensão de Arquivo
Usa a extensão de arquivo .jsonl. Este é o padrão para arquivos de fine-tuning da OpenAI, datasets do Hugging Face e a maioria das ferramentas ML/AI. GitHub e VS Code reconhecem arquivos .jsonl com destaque de sintaxe.
Usa a extensão de arquivo .ndjson. Isso é comum em ferramentas de engenharia de dados, APIs em lote do Elasticsearch e respostas HTTP de streaming. Muitos editores também suportam destaque de sintaxe .ndjson.
3. Tipo MIME
Nenhum tipo MIME oficialmente registrado. Tipos não oficiais comuns incluem application/jsonl e application/json-lines. Na prática, muitos sistemas usam application/jsonl ou recorrem a application/json.
Usa application/x-ndjson como seu tipo MIME. Este é mais amplamente reconhecido em contextos HTTP e é usado pelo Elasticsearch, o padrão de streaming da Fetch API e vários frameworks web para respostas de streaming.
4. Adoção da Comunidade e Ecossistema
Dominante no ecossistema AI/ML. OpenAI, Anthropic, Google Gemini, Hugging Face e a maioria dos frameworks ML usam .jsonl. O termo 'JSONL' é mais comumente pesquisado e reconhecido na comunidade de desenvolvedores em geral.
Preferido em engenharia de dados e sistemas backend. Elasticsearch, Apache Spark, PostgreSQL COPY e muitas ferramentas de agregação de logs usam NDJSON. O pacote npm ndjson tem milhões de downloads semanais.
Quando Usar JSONL vs NDJSON
- Preparar dados de treinamento para OpenAI, Anthropic ou outros fine-tuning de LLM
- Trabalhar com datasets do Hugging Face
- Construir pipelines de ML e pré-processamento de dados
- Sua equipe ou documentação se refere a 'JSON Lines'
- Fazer upload de arquivos para plataformas AI/ML que esperam extensão .jsonl
- Trabalhar em ambientes de ciência de dados Python
- Fazer streaming de dados JSON sobre HTTP (Server-Sent Events, fetch streaming)
- Trabalhar com a API em lote do Elasticsearch
- Construir pipelines de dados com Apache Spark ou ferramentas similares
- Definir cabeçalhos Content-Type (application/x-ndjson)
- Sua infraestrutura ou equipe usa a convenção NDJSON
- Trabalhar com bibliotecas de streaming Node.js
Exemplos de Código: Lendo JSONL e NDJSON
# Lendo JSONL - exatamente igual a ler NDJSONimport jsonwith open('data.jsonl', 'r') as f:for line in f:record = json.loads(line.strip())print(record['text'])# Output:# Hello world# How are you?# Goodbye
// Lendo NDJSON - exatamente igual a ler JSONLimport { createReadStream } from 'fs';import { createInterface } from 'readline';const rl = createInterface({input: createReadStream('data.ndjson')});for await (const line of rl) {const record = JSON.parse(line);console.log(record.text);}// Output:// Hello world// How are you?// Goodbye