CSV vs JSON - quando usar cada formato de dados

Publicado em 20 de abril de 2026

---

CSV e JSON são os dois formatos de intercâmbio de dados que quase toda ferramenta da stack moderna fala. CSV é linhas e colunas; JSON é objetos e arrays aninhados. A divisão entre eles é mais nítida do que parece: CSV é tabular por design, e qualquer coisa que o estique (vírgulas em campos, dados aninhados, células faltantes) se torna um problema de parsing. JSON é estruturado por design, e qualquer coisa que o achate (um milhão de registros de usuário em uma única lista) se torna um problema de memória. Este guia cobre a mecânica, a realidade de tamanho e velocidade, e as decisões concretas que determinam qual formato vence para cada caso de uso.

O que cada formato realmente é

CSV (valores separados por vírgula) é um formato em texto puro: um registro por linha, campos separados por um delimitador (vírgula, tabulação, ponto e vírgula ou pipe), linha de cabeçalho opcional, aspas em campos opcionais. Não há uma única especificação formal - RFC 4180 codificou o subconjunto comum em 2005, mas o CSV do mundo real varia em delimitador, caractere de aspas, regras de escape, codificação, e se linhas em branco são permitidas.

JSON (JavaScript Object Notation) é um formato estruturado recursivo: objetos (mapas chave-valor), arrays (listas ordenadas), strings, números, booleanos e null. A especificação formal é curta (RFC 8259); toda linguagem moderna traz um parser JSON na biblioteca padrão; a interoperabilidade é quase universal.

Comparação lado a lado

Quando CSV vence

Dados tabulares com esquema estável. Exportações de usuários de um banco de dados, logs de transações, registros censitários, dumps de analytics - qualquer coisa naturalmente em linhas e colunas é menor e mais rápida de parsear como CSV.

Idas e voltas para planilha. Se um stakeholder vai abrir o arquivo no Excel, Google Planilhas ou Numbers, CSV é o formato que vai e volta sem surpresas. JSON abre em um editor de texto; poucos não-desenvolvedores conseguem ler um arquivo JSON de 5.000 linhas.

Streaming de grandes datasets. Processar um arquivo de 10 GB uma linha por vez é idiomático em CSV: leia uma linha, parse, emita, descarte. JSON Lines atinge o mesmo, mas JSON puro (um único array de nível superior) requer o arquivo inteiro em memória para ser parseado corretamente.

Cargas em data warehouse. Todo warehouse (BigQuery, Snowflake, Redshift, DuckDB) tem um loader CSV otimizado. Loaders JSON existem mas são tipicamente mais lentos por causa da ambiguidade de forma.

Quando JSON vence

Dados aninhados ou hierárquicos. Um registro de usuário com uma lista de pedidos passados, cada pedido com uma lista de itens de linha, cada item de linha com uma lista de variantes - JSON expressa isto em um objeto; CSV requer ou desnormalização (uma linha por item de linha, cabeçalho repetido) ou strings JSON embutidas em células (o pior dos dois formatos).

APIs HTTP. Toda API REST e GraphQL na web moderna retorna JSON. É o padrão. Não retorne CSV de uma API a menos que o chamador explicitamente peça.

Arquivos de configuração. Valores tipados (booleanos, nulls, números) importam em configuração - CSV requereria parsing de cada campo como string e cast, convidando bugs de tipo. JSON preserva tipos. YAML preserva tipos e adiciona comentários - frequentemente a melhor escolha para configuração editada por humanos.

Registros heterogêneos. Se seus dados têm campos opcionais, formas polimórficas, ou registros com esquemas diferentes, a liberdade do JSON mapeia naturalmente; CSV força a união de todas as colunas com espaços em branco onde um campo está ausente.

O intermediário: JSON Lines (NDJSON)

JSON Lines (também chamado NDJSON) é um objeto JSON por linha de um arquivo de texto:

{"user":"alice","age":30,"tags":["admin","paid"]}
{"user":"bob","age":25,"tags":["free"]}
{"user":"carol","age":42,"tags":["paid"]}

Ele retém a tipagem e o aninhamento do JSON enquanto permite streaming linha por linha como CSV. A maioria das ferramentas de processamento de log, data warehouses, e processadores de stream aceitam nativamente. Escolha JSON Lines quando você precisa da flexibilidade de forma do JSON e da amigabilidade de streaming do CSV.

Pegadinhas comuns ao escolher CSV

Vírgulas em campos. Se qualquer campo pode conter vírgula (endereços, descrições, nomes de produto), o campo deve estar entre aspas. Parsers ingênuos split(',') quebram imediatamente. Use um parser CSV real (Python csv, Node fast-csv, Go encoding/csv).

Codificação. Excel no Windows usa UTF-16 LE com BOM por padrão; a maioria das ferramentas espera UTF-8. Sempre especifique codificação ao exportar; adicione um BOM UTF-8 se a interoperação com Excel importa.

Formatos de data. "2026-04-20" e "04/20/2026" são ambos ambíguos sem região. Prefira ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) e documente o fuso. Veja nosso guia de unix timestamps para a alternativa epoch.

Quebras de linha à direita + BOM. Alguns escritores CSV adicionam ambos; alguns parsers silenciosamente adicionam um registro em branco ou um campo ilegível. Teste ida e volta em uma amostra representativa.

Convertendo entre formatos

Conversão no navegador é viável para arquivos pequenos a médios. Para inspeção de estrutura JSON, nosso hub de ferramentas de desenvolvedor liga a jsonparser, text-diff e minificadores. Para CSV, use pandas.read_csv / pandas.to_json localmente para arquivos > 100 MB; a memória do navegador limita a conversão em ~500 MB por aba na prática.

A regra de decisão CSV vs JSON em uma sentença

Se suas linhas cabem em uma única linha de cabeçalho de nomes de coluna e um usuário de planilha está pelo menos possivelmente downstream, envie CSV - o formato é o menor denominador comum de exportação que toda ferramenta de BI, todo loader de banco de dados, e Excel consegue ingerir sem código. Se qualquer linha precisa de objetos aninhados, arrays ou números / booleanos / nulls tipados preservados no round-trip, envie JSON, e mude para JSON Lines (`.jsonl`) quando o arquivo é grande o suficiente para que um único array de nível superior forçaria o consumidor a carregar o documento inteiro em memória de uma vez. Os dois formatos não são intercambiáveis: CSV perde tipos e aninhamento na saída, e JSON ganha uma dependência de parser que a equipe de planilha pode não ter na entrada.

Ferramentas relacionadas

• Text Diff - comparar duas exportações CSV ou JSON.
• Editor de Texto / HTML - cole e renderize saída formatada.
• Minificador JavaScript - comprimir código produtor de JSON.
• Conversor MD5 - impressão digital de um arquivo de dados exportado.

← Voltar para Ferramentas para Desenvolvedores