JSONL vs NDJSON: qual é a diferença?
Um guia completo que compara JSONL (JSON Lines) e NDJSON (Newline Delimited JSON): dois nomes para praticamente o mesmo formato, com diferenças sutis que vale a pena conhecer.
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 de IA/ML | Elasticsearch, Apache Spark, engenharia de dados |
O que é JSONL (JSON Lines)?
JSONL, abreviação de JSON Lines, é um formato de dados em texto no qual 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 tem uma definição informal em jsonlines.org.
Os arquivos JSONL usam a extensão .jsonl. O formato se tornou o padrão para dados de treinamento de IA e ML: a OpenAI exige arquivos .jsonl para fine-tuning, e os datasets do Hugging Face costumam usar 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 no qual cada linha contém um valor JSON válido, com as linhas separadas por caracteres de quebra de linha. A especificação está hospedada em github.com/ndjson/ndjson-spec e foi formalizada para oferecer um padrão mais estruturado para dados JSON delimitados por quebras de linha.
Os arquivos NDJSON usam a extensão .ndjson e têm application/x-ndjson como tipo MIME registrado. O formato é amplamente adotado em engenharia de dados, processamento de logs e aplicações de streaming: Elasticsearch, Apache Spark e muitas APIs de streaming HTTP 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, com as linhas separadas por caracteres de quebra de linha (\n). Um arquivo .jsonl e um arquivo .ndjson com os mesmos dados podem ser usados de forma totalmente intercambiável, e qualquer ferramenta que leia um formato consegue ler o outro.
As diferenças se limitam aos nomes, à adoção pelas comunidades e às convenções de metadados. JSONL (JSON Lines) surgiu na 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 na web. Pense nos termos em inglês "movie" e "film": os dois se referem à mesma coisa, mas cada comunidade prefere um nome.
As diferenças mais relevantes são a extensão de arquivo (.jsonl vs .ndjson) e o tipo MIME. O tipo MIME do NDJSON (application/x-ndjson) é mais amplamente reconhecido e usado em streaming HTTP, enquanto os arquivos JSONL são o padrão nos 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 por uma especificação concisa e informal. As regras são simples: cada linha contém um valor JSON válido, as linhas são separadas por '\n' e recomenda-se a codificação UTF-8.
Definido em github.com/ndjson/ndjson-spec por uma especificação um pouco mais formal. O NDJSON exige explicitamente que cada linha contenha um valor JSON válido e que o separador de linha seja '\n' (não '\r\n'). Também recomenda uma quebra de linha ao final do arquivo.
2. Extensão de arquivo
Usa a extensão .jsonl, que é o padrão para arquivos de fine-tuning da OpenAI, datasets do Hugging Face e a maioria das ferramentas de ML/IA. GitHub e VS Code reconhecem arquivos .jsonl e oferecem realce de sintaxe.
Usa a extensão .ndjson, comum em ferramentas de engenharia de dados, APIs de operações em lote do Elasticsearch e respostas HTTP em streaming. Muitos editores também oferecem realce de sintaxe para arquivos .ndjson.
3. Tipo MIME
Não tem um tipo MIME oficialmente registrado. Entre os tipos não oficiais mais comuns estão application/jsonl e application/json-lines. Na prática, muitos sistemas usam application/jsonl ou, como alternativa, application/json.
Usa o tipo MIME application/x-ndjson, mais amplamente reconhecido em contextos HTTP. Ele é usado pelo Elasticsearch, pelo padrão de streaming da Fetch API e por vários frameworks web para respostas em streaming.
4. Adoção pela comunidade e pelo ecossistema
Predomina no ecossistema de IA/ML. OpenAI, Anthropic, Google Gemini, Hugging Face e a maioria dos frameworks de ML usam .jsonl. Na comunidade de desenvolvedores em geral, o termo 'JSONL' é mais pesquisado e mais conhecido.
É o preferido em engenharia de dados e sistemas de backend. Elasticsearch, Apache Spark, PostgreSQL COPY e muitas ferramentas de agregação de logs usam NDJSON. O pacote ndjson do npm tem milhões de downloads por semana.
Quando usar JSONL ou NDJSON
- Estiver preparando dados de treinamento para fine-tuning de LLMs da OpenAI, da Anthropic ou de outros fornecedores
- Estiver trabalhando com datasets do Hugging Face
- Estiver criando pipelines de ML e de pré-processamento de dados
- Sua equipe ou a documentação usar o termo 'JSON Lines'
- Estiver enviando arquivos para plataformas de IA/ML que exigem a extensão .jsonl
- Estiver trabalhando em ambientes Python de ciência de dados
- Estiver transmitindo dados JSON por HTTP em streaming (Server-Sent Events, fetch streaming)
- Estiver trabalhando com a API de operações em lote do Elasticsearch
- Estiver criando pipelines de dados com Apache Spark ou ferramentas semelhantes
- Estiver definindo cabeçalhos Content-Type (application/x-ndjson)
- Sua infraestrutura ou equipe usar a convenção NDJSON
- Estiver trabalhando com bibliotecas de streaming do Node.js
Exemplos de código: como ler JSONL e NDJSON
# Lendo JSONL - exatamente igual a ler NDJSON
import json
with 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 JSONL
import { 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?
// GoodbyeValide seus arquivos JSONL / NDJSON
Verifique se o seu arquivo .jsonl ou .ndjson está formatado corretamente. Nosso validador gratuito confere se cada linha tem uma sintaxe JSON válida.
Tudo sobre NDJSON: especificação, tipo MIME, leitura e escrita em Python e Node.js, APIs HTTP com streaming, ferramentas do ecossistema e a relação entre NDJSON e JSONL.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
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.
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.
Uma comparação detalhada entre os formatos JSON e JSONL. Entenda quando usar cada um, suas vantagens e desvantagens e como converter de um formato para o outro.