Por Jerry Fan

O que é JSONL? Guia completo do formato JSON Lines

Tudo o que você precisa saber sobre JSON Lines: sintaxe, exemplos, casos de uso e boas práticas.

O que é JSONL?

JSONL (JSON Lines), também conhecido como Newline Delimited JSON (NDJSON), é um formato de dados em texto no qual cada linha contém um valor JSON válido. As linhas são separadas por caracteres de quebra de linha. Enquanto o JSON padrão reúne os dados em um único array ou objeto, o JSONL armazena um registro por linha.

Essa estrutura simples torna o JSONL ideal para streaming, logs e processamento de grandes conjuntos de dados: cada linha pode ser lida, interpretada e processada de forma independente, sem carregar o arquivo inteiro na memória.

O formato se popularizou com ferramentas e plataformas que trabalham com grandes volumes de dados, como a OpenAI (em conjuntos de dados para fine-tuning), o BigQuery, o Apache Spark e sistemas de gerenciamento de logs.

Regras de sintaxe do JSONL

O formato JSONL segue algumas regras simples:

  • Cada linha deve conter um valor JSON válido (objeto, array, string, número, booleano ou null)
  • As linhas são separadas por caracteres de quebra de linha (\n)
  • Não se usam vírgulas nem outros separadores entre as linhas
  • Os arquivos devem usar a codificação UTF-8
  • A quebra de linha no final do arquivo é opcional
  • A maioria dos parsers ignora linhas vazias
Arquivo JSONL válido
{"name":"Alice","age":30,"city":"New York"}
{"name":"Bob","age":25,"city":"London"}
{"name":"Charlie","age":35,"city":"Tokyo"}

Observação: cada linha é um objeto JSON completo e independente. Não há vírgulas entre as linhas, nem um array que agrupe os objetos.

Exemplos de JSONL

Objetos simples
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","email":"[email protected]"}
{"id":3,"name":"Charlie","email":"[email protected]"}
Objetos aninhados
{"user":{"name":"Alice","age":30},"scores":[95,87,92]}
{"user":{"name":"Bob","age":25},"scores":[88,91,76]}

As linhas de um arquivo JSONL não precisam conter valores do mesmo tipo: basta que cada linha seja um JSON válido.

Tipos variados
{"event":"login","user":"alice","timestamp":"2026-01-15T10:30:00Z"}
{"event":"purchase","user":"alice","amount":29.99,"items":["book","pen"]}
{"event":"logout","user":"alice","timestamp":"2026-01-15T11:45:00Z"}

Um dos usos mais comuns do JSONL é em conjuntos de dados para fine-tuning na OpenAI:

PopularFormato para fine-tuning na OpenAI
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is JSONL?"},{"role":"assistant","content":"JSONL is a text format where each line is a valid JSON value."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"How do I read a JSONL file?"},{"role":"assistant","content":"Read the file line by line, parsing each line as JSON."}]}

Como ler arquivos JSONL

Você pode ler arquivos JSONL com qualquer ferramenta que processe texto linha por linha. Estes são os métodos mais comuns:

Use as ferramentas padrão do Unix para examinar arquivos JSONL:

Linha de comando
# View first 5 lines
head -n 5 data.jsonl


# Count total lines (records)
wc -l data.jsonl


# Pretty-print each line with jq
cat data.jsonl | jq .


# Filter by field value
cat data.jsonl | jq 'select(.age > 30)'

O módulo json, que já vem com o Python, permite trabalhar com JSONL de forma simples:

Python
import json


with open('data.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line)
        print(record['name'])

Leia arquivos JSONL linha por linha no Node.js:

JavaScript / Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.jsonl')
});


for await (const line of rl) {
  const record = JSON.parse(line);
  console.log(record.name);
}

Visualizador online de JSONL

Se preferir uma interface visual, use o jsonl.co para abrir e explorar arquivos JSONL de até 1 GB. Tudo é executado no seu navegador, sem enviar os arquivos.

Como criar arquivos JSONL

Criar um arquivo JSONL é simples: basta escrever um valor JSON por linha.

Python
import json


records = [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25},
    {"name": "Charlie", "age": 35},
]


with open('output.jsonl', 'w') as f:
    for record in records:
        f.write(json.dumps(record) + '\n')
JavaScript / Node.js
import { writeFileSync } from 'fs';


const records = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 },
];


const jsonl = records
  .map(r => JSON.stringify(r))
  .join('\n');


writeFileSync('output.jsonl', jsonl + '\n');

É possível adicionar comentários em JSONL?

Não. A especificação do JSONL não permite comentários. Cada linha de um arquivo JSONL deve conter um valor JSON válido, e o próprio JSON não tem sintaxe para comentários.

Se você precisar incluir metadados ou anotações junto aos dados, algumas alternativas comuns são:

  • 1Adicionar um campo de metadados aos objetos JSON: {"_comment": "dados de teste", "name": "Alice"}
  • 2Usar um arquivo de metadados separado, junto ao arquivo JSONL
  • 3Incluir os metadados na primeira linha do arquivo: {"_meta": {"version": "1.0", "created": "2026-01-15"}}

Lembre-se de que qualquer campo de "comentário" será interpretado como um dado comum. As aplicações que leem o arquivo JSONL devem ser preparadas para ignorar os campos de metadados.

JSONL vs JSON

A principal diferença está na estrutura. O JSON reúne todos os dados em um único valor, enquanto o JSONL armazena um valor por linha.

JSONJSON padrão
[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25}
]
JSONLJSONL (JSON Lines)
{"name":"Alice","age":30}
{"name":"Bob","age":25}
  • Para interpretar um arquivo JSON, é preciso carregá-lo inteiro na memória; um arquivo JSONL pode ser lido linha por linha
  • O JSON exige vírgulas entre os elementos; o JSONL usa quebras de linha
  • O JSON é mais adequado para arquivos de configuração e APIs; o JSONL, para grandes conjuntos de dados e streaming
  • Para acrescentar dados a um arquivo JSON, é preciso reescrever o arquivo inteiro; no JSONL, basta adicionar uma linha

Para uma comparação detalhada, consulte nosso guia completo JSON vs JSONL guide.

Casos de uso comuns

Aprendizado de máquina e IA

Mais popular

JSONL é o formato padrão para dados de treinamento de machine learning. A OpenAI, a Hugging Face e outras plataformas de IA usam JSONL em conjuntos de dados para fine-tuning porque cada exemplo de treinamento ocupa uma linha independente. Isso permite embaralhar os exemplos, selecionar amostras e transmiti-los por streaming de forma eficiente.

Arquivos de log e fluxos de eventos

JSONL

Sistemas de logs estruturados (ELK stack, Datadog, CloudWatch) geram logs em formato JSONL. Cada entrada de log ocupa uma linha com um valor JSON, o que facilita a inclusão de novas entradas e o processamento dos logs em tempo real.

Processamento de Big Data

JSONL

Ferramentas como Apache Spark, BigQuery e AWS Athena têm suporte nativo a JSONL. A organização em linhas permite o processamento paralelo em sistemas distribuídos: cada worker pode processar um bloco de linhas de forma independente.

APIs de streaming

JSONL

APIs que retornam grandes conjuntos de resultados costumam usar streaming em JSONL. O cliente pode começar a processar os resultados assim que eles chegam, sem esperar pela resposta completa.

Extensões de arquivo JSONL

Arquivos JSONL costumam usar estas extensões:

.jsonlA extensão padrão do JSONL e a mais usada
.ndjsonNewline Delimited JSON: tecnicamente, o mesmo formato com outro nome
.jsonAlgumas ferramentas geram arquivos JSONL com a extensão .json, o que pode causar confusão

As três extensões representam o mesmo formato: um valor JSON por linha. O tipo MIME do JSONL é application/jsonl ou application/x-ndjson.

Experimente nosso visualizador de JSONL

Abra, visualize e edite arquivos JSONL de até 1 GB diretamente no seu navegador. Sem enviar arquivos, com 100% de privacidade.

Perguntas frequentes

Referências