CSV e JSON são provavelmente os dois formatos de dados mais comuns que você encontrará como desenvolvedor. Arquivos CSV aparecem em exportações de planilhas, dumps de banco de dados e pipelines de ciência de dados. JSON está em todo lugar na web — APIs REST, arquivos de configuração, bancos de dados NoSQL. Ambos são texto simples, ambos são legíveis por humanos, e ambos realizam o trabalho. Mas foram construídos para diferentes formatos de dados, e escolher o errado cria dores de cabeça reais. Este artigo percorre as diferenças centrais, mostra exemplos concretos de onde cada formato brilha (e quebra), e fornece um guia de decisão prático para escolher entre eles.

A Diferença Central: Tabelas vs Árvores

CSV — definido na RFC 4180 — é um formato plano e tabular. Cada linha tem as mesmas colunas, cada valor é uma string. É isso. Mapeia perfeitamente para uma planilha ou tabela de banco de dados: linhas para baixo, colunas para os lados.

JSON — especificado na RFC 8259 e descrito em json.org — é um formato hierárquico. Valores podem ser objetos, arrays, strings, números, booleanos ou null. Objetos se aninham dentro de objetos, arrays contêm diferentes formas. Mapeia para como os dados realmente existem no código — registros com relacionamentos, listas de coisas diferentes, valores tipados.

Resumo em uma linha: CSV é uma tabela. JSON é uma árvore. Se seus dados são uma tabela, CSV é mais simples e menor. Se seus dados têm qualquer aninhamento, o CSV vai perder informações ou forçá-lo a soluções alternativas dolorosas.

Os Mesmos Dados em Ambos os Formatos

Aqui é onde a diferença se torna concreta. Imagine um catálogo de produtos para uma loja de e-commerce. Os produtos têm nome, preço e se estão em estoque — simples. Mas também têm variantes (tamanhos, cores) e atributos (material, peso). Vamos ver como esses dados se parecem em ambos os formatos.

Em JSON, isso é natural:

json
[
  {
    "id": "SHOE-001",
    "name": "Trail Runner Pro",
    "price": 129.99,
    "inStock": true,
    "attributes": {
      "material": "mesh",
      "weightGrams": 280
    },
    "variants": [
      { "size": 9,  "color": "black", "sku": "TR-9-BLK",  "qty": 12 },
      { "size": 9,  "color": "white", "sku": "TR-9-WHT",  "qty": 4  },
      { "size": 10, "color": "black", "sku": "TR-10-BLK", "qty": 7  }
    ]
  },
  {
    "id": "SHOE-002",
    "name": "City Walker",
    "price": 89.99,
    "inStock": true,
    "attributes": {
      "material": "leather",
      "weightGrams": 340
    },
    "variants": [
      { "size": 8,  "color": "brown", "sku": "CW-8-BRN",  "qty": 6  },
      { "size": 9,  "color": "brown", "sku": "CW-9-BRN",  "qty": 15 }
    ]
  }
]

Agora tente colocar isso em um CSV. Você tem duas opções, ambas desajeitadas. Opção um: achate tudo e repita os dados do pai para cada linha de variante:

csv
product_id,product_name,price,inStock,material,weightGrams,variant_size,variant_color,sku,qty
SHOE-001,Trail Runner Pro,129.99,true,mesh,280,9,black,TR-9-BLK,12
SHOE-001,Trail Runner Pro,129.99,true,mesh,280,9,white,TR-9-WHT,4
SHOE-001,Trail Runner Pro,129.99,true,mesh,280,10,black,TR-10-BLK,7
SHOE-002,City Walker,89.99,true,leather,340,8,brown,CW-8-BRN,6
SHOE-002,City Walker,89.99,true,leather,340,9,brown,CW-9-BRN,15

O nome do produto, preço e atributos são repetidos para cada variante. Isso é redundância de dados — não é grande coisa para cinco linhas, mas para um catálogo de 50.000 produtos com 8 variantes cada, se acumula. Opção dois: serializar as variantes como uma string JSON dentro de uma coluna CSV — mas agora você está incorporando JSON dentro de CSV para contornar as limitações do CSV, o que é um código malcheiroso se já vi um.

Onde o CSV Vence

Apesar dessa limitação, o CSV é genuinamente a melhor escolha em vários cenários comuns.

  • Planilhas e ferramentas de BI. Excel, Google Sheets, Tableau, Looker, Power BI — todos abrem CSV nativamente com um clique. Sem assistente de importação, sem esquema para definir, sem etapa de transformação. Se seus stakeholders vivem em planilhas, o CSV é o caminho de menor resistência.
  • Dados puramente planos. Se seus dados são genuinamente uma tabela — eventos de análise, logs de transações, leituras de sensores, exportação de usuários — o CSV é menor e mais simples. Sem chaves repetidas, sem colchetes, sem ruído.
  • Importação/exportação de banco de dados. Todo banco de dados SQL tem um comando COPY FROM CSV ou equivalente. É o formato de intercâmbio padrão para carregamento em massa de dados e é ordens de magnitude mais rápido que instruções INSERT.
  • pandas e ciência de dados. pandas.read_csv() é uma das funções mais usadas no trabalho de dados em Python. Todo o ecossistema — NumPy, scikit-learn, Polars — trata CSV como formato de entrada de primeira classe.
  • Tamanho de arquivo para grandes tabelas planas. Sem nomes de chave em cada linha, o CSV é menor para tabelas largas com muitas linhas. Um CSV de um milhão de linhas de eventos de análise confortavelmente superará o array JSON equivalente.

Onde o JSON Vence

  • Dados aninhados e hierárquicos. Assim que seus dados têm qualquer estrutura além de uma tabela plana — objetos aninhados, arrays de diferentes formas, registros relacionados — o JSON lida com isso naturalmente. O CSV não pode representar isso sem perder informações ou criar redundância.
  • Preservação de tipos. Em CSV, tudo é uma string. true, 42, null e "true" parecem iguais. Você tem que inferir tipos no lado receptor, o que leva a bugs. JSON tem booleanos, números e null nativos. inStock: true é inequivocamente um booleano — sem adivinhação necessária.
  • APIs REST e a web. JSON é o formato de dados nativo da web. Toda biblioteca cliente HTTP, toda Fetch API do navegador, toda API REST e GraphQL fala JSON. Enviar CSV via HTTP é possível, mas incomum — você precisaria de análise personalizada em ambas as extremidades.
  • Bancos de dados NoSQL. MongoDB, DynamoDB, Firestore, Elasticsearch, CouchDB — todos usam JSON (ou um superconjunto binário como BSON) como formato de documento nativo. Você insere JSON, obtém JSON de volta.
  • Arquivos de configuração. package.json, tsconfig.json, manifest.json — configuração de ferramentas padronizou em JSON porque suporta estruturas aninhadas e é fácil de gerar e validar programaticamente.
  • Validação de esquema. JSON Schema permite definir a forma exata de um documento e validar dados contra ele — verificações de tipo, campos obrigatórios, correspondência de padrões, restrições de array. O CSV não tem padrão equivalente.

Tamanho de Arquivo: A História Real

A afirmação "CSV é menor" é verdadeira em um caso específico: grandes tabelas planas com muitas linhas. Pegue 100.000 eventos de análise, cada um com oito campos fixos. Em CSV, os nomes dos campos aparecem uma vez no cabeçalho. Em JSON, aparecem em cada objeto. Essa repetição se acumula — o array JSON pode ser 30–50% maior que o CSV equivalente.

Mas inverta o cenário para dados aninhados e a matemática muda. O CSV achatado do nosso catálogo de calçados repete o nome do produto, preço e atributos em cada linha de variante. A versão JSON armazena cada produto uma vez. Para dados profundamente aninhados com muitos campos de pai repetidos, o JSON pode realmente ser menor.

Na prática, se o tamanho do arquivo é uma preocupação real, ambos os formatos comprimem extremamente bem com gzip — os nomes de chave repetitivos em JSON e os valores de linha repetidos em CSV ambos comprimem muito. Servir JSON comprimido com gzip via HTTP é prática padrão, e a diferença de tamanho geralmente torna-se negligenciável após a compressão.

Comparação de Ferramentas

A história de ferramentas para cada formato reflete onde é mais usado.

Ferramentas CSV: Excel, Google Sheets e LibreOffice Calc abrem nativamente. A biblioteca pandas torna o CSV o padrão para análise de dados em Python. Todo banco de dados relacional tem um comando de importação/exportação CSV. Ferramentas de linha de comando como csvkit e xsv permitem filtrar, unir e agregar arquivos CSV sem escrever código. O tipo MIME é text/csv, registrado na IANA.

Ferramentas JSON: Toda linguagem de programação tem um analisador JSON embutido ou de biblioteca padrão. JSON.parse() em JavaScript, json.loads() em Python, encoding/json em Go, serde_json em Rust. A referência JSON do MDN é uma das páginas mais visitadas do MDN. Linha de comando: jq é indispensável para consultar e transformar JSON. IDEs fazem pretty-print e validam automaticamente.

Se você está trabalhando com pipelines de dados que abrangem ambos os mundos — carregando respostas JSON de API em um data warehouse, ou exportando registros de banco de dados para uma planilha — você converterá regularmente entre os dois. O conversor CSV para JSON e conversor JSON para CSV lidam com isso rapidamente. Para organizar arquivos brutos antes de processar, o Formatador CSV e Formatador JSON valem a pena marcar nos favoritos.

O Híbrido: JSON Lines (NDJSON)

Há uma terceira opção que vale a pena conhecer: JSON Lines, também chamado de NDJSON (JSON Delimitado por Nova Linha). A ideia é simples — um objeto JSON completo por linha, sem array circundante.

json
{"id":"SHOE-001","name":"Trail Runner Pro","price":129.99,"inStock":true,"variantCount":3}
{"id":"SHOE-002","name":"City Walker","price":89.99,"inStock":true,"variantCount":2}
{"id":"SHOE-003","name":"Summit Hiker","price":159.99,"inStock":false,"variantCount":5}

Este formato oferece o melhor dos dois mundos para certos casos de uso. Como CSV, você pode fazer streaming e processar linha a linha sem carregar o arquivo inteiro na memória — crítico para grandes arquivos de log ou saídas de pipeline de dados. Como JSON, cada linha pode ter um esquema diferente e preserva tipos. Você pode usar ferramentas Unix padrão (grep, wc -l, head) para trabalhar com ele, mas também canalizar cada linha pelo jq para consultas estruturadas.

NDJSON é amplamente usado para agregação de logs (é o formato de saída padrão de muitos loggers estruturados), estágios de pipeline de dados e exportações de dados de treinamento de ML. Se você está escrevendo um script que processa milhões de registros e cada registro é um objeto JSON, NDJSON é geralmente a escolha certa em vez de um array JSON gigante — você evita carregar tudo na memória e pode retomar a partir de um checkpoint facilmente.

python
import json

# Process a large NDJSON file without loading it all into memory
with open('products.ndjson', 'r') as f:
    for line in f:
        product = json.loads(line.strip())
        if product['inStock'] and product['price'] < 100:
            print(f"{product['name']} — ${product['price']}")

Guia de Decisão: CSV vs JSON

Aqui está a versão prática. Quando você está escolhendo entre os dois, faça a si mesmo essas perguntas:

  • Seus dados são genuinamente planos (sem aninhamento, sem arrays)? Se sim, CSV é mais simples. Se não, JSON.
  • Um não-desenvolvedor vai consumir este arquivo? Analistas no Excel? Usuários de negócios no Google Sheets? Use CSV.
  • Você está servindo ou consumindo uma API HTTP? Use JSON. Ponto final.
  • Você está fazendo uma importação ou exportação em massa de banco de dados? Use CSV — todo banco de dados o suporta nativamente.
  • Os dados têm tipos mistos (booleanos, números, nulls)? Use JSON para evitar bugs de inferência de tipos no lado receptor.
  • O arquivo será processado linha a linha em um pipeline de streaming? Considere NDJSON como um meio-termo.
  • Você está armazenando configuração? Use JSON (ou YAML se comentários importam para você).
  • O esquema precisa variar por registro? JSON. CSV impõe as mesmas colunas em cada linha.
O padrão honesto: Se você está construindo algo para outros desenvolvedores ou máquinas consumirem, use JSON. Se está entregando dados a um humano que vai abrir em uma planilha, use CSV. Se está construindo um pipeline de dados que processa milhões de registros estruturados, considere NDJSON.

Conclusão

CSV e JSON não estão realmente competindo — resolvem problemas diferentes. CSV é a ferramenta certa quando seus dados são uma tabela e você quer máxima compatibilidade com ferramentas de planilha e banco de dados. JSON é a ferramenta certa quando seus dados têm estrutura, tipos ou aninhamento, e quando você está se comunicando com APIs ou aplicações.

A decisão geralmente não é difícil uma vez que você olha para a forma real dos dados. Linhas planas de leituras de sensores? CSV. Uma resposta de API com perfis de usuário aninhados e históricos de pedidos incorporados? JSON. Um log de streaming de eventos estruturados? NDJSON. Corresponda o formato à forma dos dados e às ferramentas em cada extremidade, e raramente errará.

← All CSV articles Browse all categories →