Tutorial JSONL: Criar, Ler e Converter Arquivos JSONL

Um tutorial passo a passo cobrindo tudo que você precisa saber sobre trabalhar com arquivos JSONL (JSON Lines). Inclui exemplos de código em Python, JavaScript e ferramentas CLI.

Última atualização: fevereiro de 2026

O que é JSONL?

JSONL (JSON Lines) é um formato de texto leve onde cada linha é um valor JSON válido separado. Diferente do JSON padrão, que envolve todos os dados em um único array ou objeto, JSONL armazena um registro por linha, separados por caracteres de quebra de linha (\n).

Esta estrutura linha por linha torna o JSONL ideal para streaming de grandes datasets, anexar registros sem reescrever o arquivo e processar dados em paralelo. É amplamente usado pela OpenAI para datasets de fine-tuning, por sistemas de logging como a pilha 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 é direto: serialize cada registro como uma string JSON de linha única e escreva seguida de uma quebra de linha. Aqui estão 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`);

Manual / Editor de Texto

Você também pode criar arquivos JSONL em qualquer editor de texto. Simplesmente digite um objeto JSON válido por linha sem vírgulas entre linhas, e salve o arquivo com extensão .jsonl. Certifique-se de que cada linha seja completa e JSON válido.

Como Ler Arquivos JSONL

Como cada linha é um valor JSON independente, ler arquivos JSONL é tão simples quanto iterar sobre as linhas. Aqui estão 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, converter para JSONL significa escrever cada elemento como uma linha separada. Esta é uma das operações JSONL mais comuns.

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`);

Converter online

Não quer escrever código? Use nosso conversor JSON to JSONL online gratuito — cole ou faça upload do seu arquivo e converta instantaneamente.

Como Converter CSV para JSONL

Converter CSV para JSONL mapeia cada linha para um objeto JSON, usando o cabeçalho CSV como nomes de campos. Isso é útil ao migrar dados tabulares para um formato adequado para 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');

Converter CSV online

Converta arquivos CSV para formato JSONL instantaneamente com nossa ferramenta online gratuita — sem código.

Melhores Práticas JSONL

1

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

2

Escreva exatamente um objeto JSON por linha. Nunca divida um objeto JSON em múltiplas linhas ou coloque múltiplos objetos na mesma linha.

3

Não adicione vírgulas entre linhas. Diferente de arrays JSON, JSONL usa caracteres de quebra de linha como único delimitador.

4

Valide cada linha independentemente. Cada linha deve ser um valor JSON completo e válido. Use um validador JSONL para detectar erros de sintaxe cedo.

5

Use leituras em streaming para arquivos grandes. Em vez de carregar o arquivo inteiro na memória, processe linha por linha usando readline (Node.js) ou iteração de arquivo (Python).

6

Mantenha registros consistentes na estrutura. Embora JSONL permita diferentes schemas por linha, manter uma estrutura uniforme torna o processamento de dados muito mais fácil.

7

Evite espaços em branco finais. Certifique-se de que as linhas não tenham espaços ou tabs extras que possam causar problemas de parseamento.

8

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

Erros Comuns de JSONL

Envolver em um Array
Wrong
[
  {"name":"Alice"},
  {"name":"Bob"}
]
Correct
{"name":"Alice"}
{"name":"Bob"}

JSONL não é um array JSON. Não envolva linhas em colchetes ou adicione vírgulas entre elas. Cada linha é independente.

Vírgulas Entre Linhas
Wrong
{"name":"Alice"},
{"name":"Bob"},
Correct
{"name":"Alice"}
{"name":"Bob"}

Vírgulas finais após cada linha ou vírgulas entre linhas são inválidas em JSONL. O caractere de quebra de linha é o único separador.

Objetos JSON Multi-linha
Wrong
{
  "name": "Alice",
  "age": 30
}
Correct
{"name":"Alice","age":30}

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

Caracteres Especiais Não Escapados
Wrong
{"text":"She said "hello""}
Correct
{"text":"She said \"hello\""}

Aspas e caracteres especiais dentro de strings JSON devem ser escapados com barras invertidas. Aspas não escapadas quebrarão o parser JSON.

Validar seu JSONL

Após criar seu arquivo JSONL, valide-o para detectar erros de sintaxe cedo. Nosso validador gratuito verifica cada linha instantaneamente.

Experimente Nossas Ferramentas JSONL Gratuitas

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no seu navegador. Sem uploads necessários, 100% privado.

Perguntas Frequentes

Tutorial JSONL — Criar, Ler, Validar e Converter Arquivos...