Por Jerry Fan

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ísticaJSONL (JSON Lines)NDJSON
Nome completoJSON LinesNewline Delimited JSON
Extensão de arquivo.jsonl.ndjson
Especificaçãojsonlines.org (informal)github.com/ndjson/ndjson-spec (especificação informal)
OrigemConvenção da comunidade, popularizada por ferramentas de ciência de dadosProposto por Chris Olah, Thorsten Ball e outros
Delimitador de linha\n (quebra de linha)\n (quebra de linha)
Tipo MIMEapplication/jsonl (não oficial)application/x-ndjson
Suporte a streamingSim, linha por linhaSim, linha por linha
AdoçãoOpenAI, Hugging Face, ecossistema de IA/MLElasticsearch, 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.

data.jsonl
{"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.

data.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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

É 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

JSONLUse .jsonl quando:
  • 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
NDJSONUse .ndjson quando:
  • 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

Leitura de um arquivo .jsonl (Python)
# 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
Leitura de um arquivo .ndjson (JavaScript/Node.js)
// 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?
// Goodbye

Visualize arquivos JSONL e NDJSON na hora

Abra arquivos .jsonl e .ndjson de até 1GB no seu navegador. Sem upload nem cadastro, com suporte aos dois formatos.

Perguntas frequentes

Referências