Por Jerry Fan

JSON vs JSONL: qual é a diferença?

Um guia completo para entender os formatos JSON e JSONL (JSON Lines), as diferenças entre eles e quando usar cada um.

Comparação rápida

CaracterísticaJSONJSONL (JSON Lines)
EstruturaUm único objeto ou arrayUm objeto JSON por linha
Extensão do arquivo.json.jsonl ou .ndjson
ParsingExige o parsing do arquivo inteiroPermite fazer o parsing linha por linha
StreamingDifícilSuporte nativo
Processamento de arquivos grandesAlto consumo de memóriaBaixo consumo de memória
LegibilidadeFormatado com indentaçãoCompacto, um registro por linha
Validação com JSON SchemaSuporte a JSON SchemaJSON Schema aplicado a cada linha
Adição de dadosExige reescrever o arquivo inteiroBasta acrescentar uma nova linha

O que é JSON?

JSON (JavaScript Object Notation) é um formato leve para troca de dados, fácil de ler e escrever por pessoas e de interpretar e gerar por máquinas. Baseado em um subconjunto de JavaScript, tornou-se o padrão de fato para troca de dados na web.

Um arquivo JSON contém um único valor JSON, geralmente um objeto ou um array. Para acessar qualquer dado, é necessário fazer o parsing do arquivo inteiro como uma única unidade.

Exemplo de JSON
[
  {"name": "Alice", "age": 30, "city": "New York"},
  {"name": "Bob", "age": 25, "city": "London"},
  {"name": "Charlie", "age": 35, "city": "Tokyo"}
]

O que é JSONL (JSON Lines)?

JSONL (JSON Lines), também conhecido como Newline Delimited JSON (NDJSON), é um formato de texto em que cada linha contém um objeto JSON válido. As linhas são separadas por caracteres de nova linha (\n). Ao contrário do JSON convencional, os dados não ficam dentro de um array ou objeto que englobe todo o conteúdo.

Cada linha de um arquivo JSONL é independente e pode ser interpretada separadamente. Isso torna o JSONL ideal para streaming de dados, arquivos de log e processamento de grandes conjuntos de dados sem carregar tudo na memória.

Exemplo de JSONL
{"name": "Alice", "age": 30, "city": "New York"}
{"name": "Bob", "age": 25, "city": "London"}
{"name": "Charlie", "age": 35, "city": "Tokyo"}

Principais diferenças entre JSON e JSONL

1. Formato e estrutura do arquivo

JSON

No JSON, todos os dados ficam em um único objeto ou array. A sintaxe do arquivo precisa ser válida como um todo: se faltar um colchete no final, o arquivo inteiro será inválido.

JSONL

O JSONL armazena um objeto JSON por linha. Cada linha é independente: se houver um erro em uma delas, ainda será possível fazer o parsing das demais.

2. Parsing e uso de memória

JSON

O JSON exige carregar e fazer o parsing do arquivo inteiro de uma só vez. Para um arquivo JSON de 1 GB, seriam necessários aproximadamente 1 GB ou mais de memória.

JSONL

O JSONL permite a leitura e o parsing linha por linha (streaming). Mesmo um arquivo JSONL de 10 GB pode ser processado com consumo mínimo de memória, lendo uma linha por vez.

3. Streaming e dados em tempo real

JSON

O JSON não foi projetado para streaming. Você só pode começar a processar os dados depois de receber todo o arquivo ou toda a resposta e concluir o parsing.

JSONL

O JSONL é ideal para streaming. Cada linha pode ser processada assim que chega, o que o torna perfeito para fluxos de dados em tempo real, logs e eventos enviados pelo servidor.

4. Adição e gravação de dados

JSON

Para adicionar dados a um array JSON, é necessário ler o arquivo inteiro, fazer o parsing, incluir o novo elemento e regravar todo o arquivo.

JSONL

Para adicionar dados a um arquivo JSONL, basta acrescentar uma linha no final. Não é necessário ler nem modificar os dados existentes. Essa operação tem complexidade O(1), em comparação com O(n) no JSON.

5. Facilidade de leitura

JSON

O JSON permite formatação com indentação, o que facilita bastante a leitura de arquivos de configuração e respostas de API.

JSONL

O JSONL é compacto por definição, com um registro por linha. O formato é otimizado para o processamento por máquinas, e não para a leitura por pessoas, embora seja possível formatar cada linha individualmente para facilitar a leitura.

Quando usar JSON ou JSONL

JSONUse JSON quando:
  • Você trabalha com arquivos de configuração
  • Você cria corpos de requisições e respostas de APIs REST
  • Você armazena pequenos volumes de dados estruturados (menos de 10 MB)
  • Os dados precisam ser fáceis de ler e editar por pessoas
  • Você trabalha com estruturas de dados aninhadas e hierárquicas
  • Você troca dados no navegador
JSONLUse JSONL quando:
  • Você processa grandes conjuntos de dados (100 MB ou mais)
  • Você transmite dados em tempo real
  • Você grava arquivos de log e dados de eventos
  • Você treina modelos de aprendizado de máquina (OpenAI, Hugging Face)
  • Você trabalha com pipelines de ETL e processamento de dados
  • Você adiciona dados com frequência
  • Você processa dados com ferramentas Unix (grep, awk, sed)

Casos de uso comuns

Aprendizado de máquina e IA

JSONL

O JSONL é o formato padrão para dados de treinamento de modelos de aprendizado de máquina (ML). A OpenAI usa JSONL em conjuntos de dados para fine-tuning, e muitos frameworks de ML esperam receber dados nesse formato. Cada linha representa um exemplo de treinamento.

Logs de aplicações

JSONL

O JSONL é uma escolha natural para logs de servidor, eventos de aplicações e trilhas de auditoria. Cada evento é gravado em uma única linha, o que facilita acrescentar novos eventos, fazer buscas com grep e processar os dados com ferramentas de streaming.

APIs web e configuração

JSON

As APIs REST geralmente usam JSON no corpo das requisições e respostas. Os arquivos de configuração (.json) usam JSON para organizar configurações de forma legível e estruturada, com objetos aninhados.

Big Data e análise

JSONL

Pipelines de dados, processos de ETL e ferramentas de análise usam JSONL para processar grandes volumes de dados. Como cada registro pode ser processado de forma independente, o formato permite o processamento paralelo e o uso de padrões MapReduce.

Exemplos de código

Leitura de JSON em JavaScript
// Reading JSON - must load entire file
const data = JSON.parse(fs.readFileSync('data.json', 'utf8'));


// Access data
data.forEach(item => {
  console.log(item.name);
});
Leitura de JSONL em JavaScript
// Reading JSONL - stream line by line
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


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


for await (const line of rl) {
  const item = JSON.parse(line);
  console.log(item.name);
}
Converter JSON para JSONL
// JSON array to JSONL
const jsonArray = JSON.parse(fs.readFileSync('data.json', 'utf8'));
const jsonl = jsonArray
  .map(item => JSON.stringify(item))
  .join('\n');
fs.writeFileSync('data.jsonl', jsonl);
Converter JSONL para JSON
// JSONL to JSON array
const lines = fs.readFileSync('data.jsonl', 'utf8')
  .split('\n')
  .filter(line => line.trim());
const jsonArray = lines.map(line => JSON.parse(line));
fs.writeFileSync('data.json', JSON.stringify(jsonArray, null, 2));

Experimente nosso visualizador de JSONL

Visualize e edite arquivos JSONL de até 1 GB na hora, direto no navegador. Sem enviar arquivos nem fazer cadastro.

Perguntas frequentes

Referências