Por Jerry Fan

Tutorial de JSONL: como criar, ler e converter arquivos JSONL

Um tutorial passo a passo com tudo o que você precisa saber para trabalhar com arquivos JSONL (JSON Lines). Inclui exemplos de código em Python e JavaScript, além de exemplos com ferramentas de linha de comando.

O que é JSONL?

JSONL (JSON Lines) é um formato de texto leve em que cada linha contém um valor JSON válido e independente. Ao contrário do JSON padrão, que reúne todos os dados em um único array ou objeto, o JSONL armazena um registro por linha, com os registros separados por caracteres de quebra de linha (\n).

Essa estrutura em linhas torna o JSONL ideal para trabalhar com grandes conjuntos de dados em streaming, acrescentar registros sem reescrever o arquivo e processar dados em paralelo. O formato é amplamente usado pela OpenAI em conjuntos de dados para fine-tuning, por sistemas de logs como a stack ELK e por ferramentas de big data como BigQuery e Apache Spark.

example.jsonl
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}

Como criar arquivos JSONL

Criar um arquivo JSONL é simples: serialize cada registro como uma string JSON em uma única linha e grave essa string seguida de uma quebra de linha. Veja exemplos nas linguagens mais populares.

Python
import json


records = [
    {"id": 1, "name": "Alice", "role": "engineer"},
    {"id": 2, "name": "Bob", "role": "designer"},
    {"id": 3, "name": "Charlie", "role": "manager"},
]


with open("output.jsonl", "w", encoding="utf-8") as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print("Created output.jsonl with", len(records), "records")
JavaScript / Node.js
import { writeFileSync } from 'fs';


const records = [
  { id: 1, name: 'Alice', role: 'engineer' },
  { id: 2, name: 'Bob', role: 'designer' },
  { id: 3, name: 'Charlie', role: 'manager' },
];


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


writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created output.jsonl with ${records.length} records`);

Criação manual em um editor de texto

Você também pode criar arquivos JSONL em qualquer editor de texto. Basta digitar um objeto JSON válido por linha, sem vírgulas entre as linhas, e salvar o arquivo com a extensão .jsonl. Confira se cada linha contém um valor JSON completo e válido.

Como ler arquivos JSONL

Como cada linha contém um valor JSON independente, basta percorrer as linhas para ler um arquivo JSONL. Veja as abordagens mais comuns.

Python
import json


with open("data.jsonl", "r", encoding="utf-8") as f:
    for line_number, line in enumerate(f, 1):
        line = line.strip()
        if not line:
            continue  # skip empty lines
        record = json.loads(line)
        print(f"Line {line_number}: {record['name']} - {record['role']}")
JavaScript / Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


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


let lineNumber = 0;
for await (const line of rl) {
  if (!line.trim()) continue; // skip empty lines
  lineNumber++;
  const record = JSON.parse(line);
  console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);
}
Linha de comando (grep / jq)
# Ver as primeiras 10 linhas
head -n 10 data.jsonl


# Contar total de registros
wc -l data.jsonl


# Imprimir cada linha de forma legível com jq
cat data.jsonl | jq .


# Filtrar registros onde role é "engineer"
cat data.jsonl | jq 'select(.role == "engineer")'


# Extrair apenas o campo name
cat data.jsonl | jq -r '.name'


# Buscar linhas contendo uma palavra-chave
grep '"Alice"' data.jsonl

Como converter JSON para JSONL

Se você tem um array JSON padrão, basta gravar cada elemento em uma linha separada para convertê-lo em JSONL. Essa é uma das operações mais comuns com JSONL.

Python
import json


# Ler array JSON
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)  # expects a JSON array


# Escrever como JSONL
with open("data.jsonl", "w", encoding="utf-8") as f:
    for record in data:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print(f"Converted {len(data)} records from JSON to JSONL")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


// Ler array JSON
const data = JSON.parse(readFileSync('data.json', 'utf-8'));


// Escrever como JSONL
const jsonl = data
  .map(record => JSON.stringify(record))
  .join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Converted ${data.length} records from JSON to JSONL`);

Converta online

Não quer escrever código? Use nosso conversor gratuito de JSON para JSONL online: cole o conteúdo ou faça upload do arquivo e converta na hora.

Como converter CSV para JSONL

Na conversão de CSV para JSONL, cada linha se torna um objeto JSON, e os valores do cabeçalho do CSV são usados como nomes dos campos. Isso é útil para migrar dados tabulares para um formato adequado a streaming ou aprendizado de máquina.

Python
import csv
import json


with open("data.csv", "r", encoding="utf-8") as csv_file:
    reader = csv.DictReader(csv_file)
    with open("data.jsonl", "w", encoding="utf-8") as jsonl_file:
        for row in reader:
            jsonl_file.write(json.dumps(row, ensure_ascii=False) + "\n")


print("Converted CSV to JSONL successfully")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


const csv = readFileSync('data.csv', 'utf-8');
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');


const jsonl = lines.slice(1).map(line => {
  const values = line.split(',');
  const obj = {};
  headers.forEach((h, i) => obj[h.trim()] = values[i]?.trim());
  return JSON.stringify(obj);
}).join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log('Converted CSV to JSONL successfully');

Converta CSV online

Converta arquivos CSV para JSONL na hora com nossa ferramenta online gratuita, sem precisar escrever código.

Boas práticas com JSONL

1

Use a codificação UTF-8 em todos os arquivos JSONL. Isso garante a compatibilidade entre plataformas e o suporte a caracteres internacionais.

2

Grave exatamente um objeto JSON por linha. Nunca divida um objeto JSON em várias linhas nem coloque vários objetos na mesma linha.

3

Não adicione vírgulas entre as linhas. Ao contrário dos arrays JSON, o JSONL usa apenas caracteres de quebra de linha como delimitadores.

4

Valide cada linha separadamente. Todas as linhas devem conter um valor JSON completo e válido. Use um validador JSONL para identificar erros de sintaxe logo no início.

5

Leia arquivos grandes em streaming. Em vez de carregar o arquivo inteiro na memória, processe uma linha por vez usando readline (Node.js) ou percorrendo as linhas do arquivo (Python).

6

Mantenha uma estrutura consistente entre os registros. Embora o JSONL permita um schema diferente por linha, uma estrutura uniforme facilita muito o processamento dos dados.

7

Evite espaços em branco no fim das linhas. Verifique se não há espaços ou tabulações extras que possam causar problemas na análise do JSON.

8

Termine o arquivo com uma quebra de linha. Uma quebra de linha após o último registro ajuda ferramentas como wc e cat a processar o arquivo corretamente.

Erros comuns em JSONL

Colocar os registros dentro de um array
Incorreto
[
  {"name":"Alice"},
  {"name":"Bob"}
]
Correto
{"name":"Alice"}
{"name":"Bob"}

JSONL não é um array JSON. Não coloque as linhas entre colchetes nem adicione vírgulas entre elas. Cada linha é independente.

Usar vírgulas entre as linhas
Incorreto
{"name":"Alice"},
{"name":"Bob"},
Correto
{"name":"Alice"}
{"name":"Bob"}

Vírgulas no fim de cada linha ou entre as linhas não são válidas em JSONL. O caractere de quebra de linha é o único separador.

Dividir objetos JSON em várias linhas
Incorreto
{
  "name": "Alice",
  "age": 30
}
Correto
{"name":"Alice","age":30}

Cada objeto JSON deve ocupar uma única linha. JSON formatado com indentação e quebras de linha não é JSONL válido.

Não escapar caracteres especiais
Incorreto
{"text":"She said "hello""}
Correto
{"text":"She said \"hello\""}

Aspas e caracteres especiais dentro de strings JSON devem ser escapados corretamente com barras invertidas. Aspas sem escape causam erros no parser JSON.

Experimente nossas ferramentas gratuitas para JSONL

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no navegador. Sem precisar fazer upload e com 100% de privacidade.

Perguntas frequentes

Referências