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
{"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
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","email":"[email protected]"}
{"id":3,"name":"Charlie","email":"[email protected]"}{"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.
{"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:
{"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:
# 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:
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:
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);
}Como criar arquivos JSONL
Criar um arquivo JSONL é simples: basta escrever um valor JSON por linha.
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')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.
[
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
]{"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 popularJSONL é 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
JSONLSistemas 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
JSONLFerramentas 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
JSONLAPIs 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:
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 nossas ferramentas JSONL gratuitas
Valide a sintaxe dos seus arquivos JSONL, converta entre formatos e visualize arquivos, tudo no seu navegador.
Visualize e edite arquivos JSONL de até 1GB instantaneamente no seu navegador. Um leitor gratuito de arquivos JSONL com streaming, realce de sintaxe e validação em tempo real. Sem uploads nem cadastro — seus dados ficam no seu dispositivo.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Formate arquivos JSONL com a indentação adequada para facilitar a leitura, a depuração e a revisão dos dados.
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.
Tutorial passo a passo para trabalhar com arquivos JSONL. Aprenda a ler, escrever e processar dados JSONL com Python, JavaScript e ferramentas de linha de comando.