Guia de conversão de CSV para JSON: métodos, erros comuns e boas práticas

Sua equipe de operações envia uma exportação em CSV. Sua API espera JSON. Você abre o arquivo, olha para 10.000 linhas de valores separados por vírgulas e se pergunta: qual é a forma mais rápida de converter CSV para JSON sem perder dados?

Este guia cobre quatro métodos de conversão (ferramentas no navegador, JavaScript, Python, CLI), a direção inversa (JSON para CSV), cinco erros comuns que corrompem seus dados silenciosamente, e como lidar com arquivos grandes demais para caber na memória.

CSV vs JSON: quando usar cada um?

Antes de converter, é útil entender no que cada formato se destaca.

Dimensão	CSV	JSON
Estrutura	Tabela plana (linhas e colunas)	Hierarquia aninhada (objetos, arrays)
Tipos de dados	Tudo é uma string de texto	string, number, boolean, null
Legibilidade	Amigável para planilhas	Amigável para desenvolvedores
Uso principal	Exportação/importação de dados, relatórios, ETL	APIs, arquivos de configuração, armazenamento NoSQL
Tamanho do arquivo	Menor (sem nomes de chave repetidos)	Maior (nomes de chave se repetem por registro)
Esquema	Implícito (linha de cabeçalho)	Explícito (ou usar JSON Schema)

Regra geral: Use CSV quando seus dados são tabulares e o consumidor é uma planilha ou um pipeline de dados. Use JSON quando seus dados têm hierarquia ou seu consumidor é uma API. Você sempre pode validar sua saída JSON com um JSON Formatter para detectar problemas estruturais cedo.

Se seu projeto usa formatos JSON relaxados como JSON5 ou JSONC para configuração, consulte nosso guia de formato JSON5 e JSONC para conhecer as diferenças de sintaxe e ferramentas.

4 formas de converter CSV para JSON

Método 1 — Ferramenta no navegador

Para conversões pontuais, uma ferramenta baseada no navegador é o caminho mais rápido. Cole seu CSV em um conversor online, obtenha JSON de saída, e depois valide o resultado em um JSON Formatter para confirmar que a estrutura está correta.

A vantagem: seus dados nunca saem do seu navegador. Sem uploads, sem processamento no servidor, sem preocupações com privacidade. Isso importa quando você trabalha com dados internos, chaves de API embutidas em exportações, ou qualquer coisa que prefira não enviar a um servidor de terceiros.

Ideal para: arquivos pequenos (menos de 10 MB), conversões rápidas de uma só vez, e membros da equipe não técnicos.

Método 2 — JavaScript / Node.js

Navegador (JavaScript puro):

function csvToJson(csv) {
  const lines = csv.trim().split('\n');
  const headers = lines[0].split(',').map(h => h.trim());

  return lines.slice(1).map(line => {
    const values = line.split(',');
    return headers.reduce((obj, header, i) => {
      obj[header] = values[i]?.trim() ?? '';
      return obj;
    }, {});
  });
}

const csv = `name,age,city
Alice,30,New York
Bob,25,London`;

console.log(JSON.stringify(csvToJson(csv), null, 2));

Isso funciona para CSV simples sem campos entre aspas. Para uso em produção com vírgulas dentro de valores, quebras de linha em campos ou strings entre aspas, use um parser adequado.

Node.js (csv-parser + streams):

import { createReadStream } from 'fs';
import { parse } from 'csv-parse';

const records = [];

createReadStream('data.csv')
  .pipe(parse({ columns: true, trim: true, skip_empty_lines: true }))
  .on('data', (row) => records.push(row))
  .on('end', () => {
    console.log(JSON.stringify(records, null, 2));
  });

A opção columns: true usa a primeira linha como chaves. A opção trim remove os espaços em branco dos valores. Isso lida corretamente com campos entre aspas, vírgulas escapadas e valores multilinha.

Método 3 — Python

Biblioteca padrão (sem dependências):

import csv
import json

with open('data.csv', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    rows = list(reader)

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(rows, f, indent=2, ensure_ascii=False)

csv.DictReader mapeia cada linha para um dicionário usando a linha de cabeçalho como chaves. A opção ensure_ascii=False preserva os caracteres Unicode (chinês, japonês, caracteres acentuados) em vez de escapá-los como \uXXXX.

Pandas (uma linha para cientistas de dados):

import pandas as pd

df = pd.read_csv('data.csv')
df.to_json('data.json', orient='records', indent=2, force_ascii=False)

Quando usar cada um:

csv + json: Scripts leves, funções Lambda, containers onde você quer dependências mínimas.
pandas: Quando também precisa limpar, filtrar ou transformar dados antes de converter. O overhead de importar pandas vale a pena quando você faz mais do que apenas conversão de formato.

Método 4 — Ferramentas CLI

Para scripts de shell e pipelines de automação:

csvkit:

# Install: pip install csvkit
csvjson data.csv > data.json

Miller (mlr):

# Install: brew install miller (macOS) or apt install miller (Ubuntu)
mlr --csv --json cat data.csv > data.json

Combinar com jq para filtrar:

# Converter e filtrar em um pipeline
csvjson data.csv | jq '[.[] | select(.age | tonumber > 25)]'

Miller é particularmente poderoso porque lida com CSV, JSON, TSV e outros formatos nativamente. Você pode transformar dados durante a conversão:

# Converter CSV para JSON, renomear um campo, adicionar um campo calculado
mlr --csv --json rename name,fullName then put '$age_group = ($age > 30) ? "senior" : "junior"' data.csv

JSON para CSV: a direção inversa

Converter JSON para CSV introduz desafios que não existem na direção direta.

Achatar objetos aninhados

CSV é inerentemente plano. Quando seu JSON tem objetos aninhados, você precisa de uma estratégia de achatamento:

{
  "name": "Alice",
  "address": {
    "city": "New York",
    "zip": "10001"
  }
}

Se torna:

name	address.city	address.zip
Alice	New York	10001

A convenção de notação com pontos (address.city) é a abordagem mais comum. Em Python:

import pandas as pd

data = [
    {"name": "Alice", "address": {"city": "New York", "zip": "10001"}},
    {"name": "Bob", "address": {"city": "London", "zip": "EC1A"}}
]

df = pd.json_normalize(data)
df.to_csv('output.csv', index=False)
# Colunas: name, address.city, address.zip

Tratamento de arrays

Campos de tipo array requerem uma decisão:

Estratégia	Entrada de exemplo	Saída CSV	Ideal para
Unir como string	`["admin","editor"]`	`admin;editor`	Listas simples, reimportáveis
Expandir para colunas	`["admin","editor"]`	`role_0: admin, role_1: editor`	Arrays de comprimento fixo
Expandir para linhas	`["admin","editor"]`	Duas linhas, uma por papel	Análise relacional

Escolha com base no seu consumidor final. Se o CSV vai de volta para um banco de dados, expandir para linhas geralmente faz mais sentido.

Perda de informação de tipos

CSV não tem sistema de tipos. Quando converte JSON para CSV:

true se torna a string "true" — é um booleano ou uma string?
null se torna uma célula vazia — indistinguível de uma string vazia ""
42 se torna "42" — é um número ou uma string?

Se a fidelidade de ida e volta é importante (CSV -> processo -> JSON), documente suas convenções de tipos em um comentário de cabeçalho ou em um arquivo de esquema complementar.

5 erros comuns e como evitá-los

Esses problemas corrompem dados silenciosamente. A maioria dos tutoriais os omite. Não os aprenda em produção.

1. Armadilhas de codificação

O problema: Você abre um CSV de um colega e vê ÃƒÂ© em vez de é, ou 锟斤拷 em vez de caracteres chineses.

Por que acontece: O arquivo foi salvo em uma codificação (Windows-1252, GBK, Shift_JIS) mas seu parser assume UTF-8. O Excel no Windows frequentemente salva CSV como Windows-1252 ou adiciona um BOM UTF-8 (Byte Order Mark — o invisível \xEF\xBB\xBF no início do arquivo).

A solução:

# Detectar a codificação primeiro
import chardet

with open('data.csv', 'rb') as f:
    result = chardet.detect(f.read(10000))
    print(result)  # {'encoding': 'Windows-1252', 'confidence': 0.73}

# Depois ler com a codificação correta
with open('data.csv', encoding=result['encoding']) as f:
    reader = csv.DictReader(f)
    # ...

Em Node.js, remova o BOM explicitamente:

import { readFileSync } from 'fs';

let content = readFileSync('data.csv', 'utf-8');
// Remover BOM UTF-8 se presente
if (content.charCodeAt(0) === 0xFEFF) {
  content = content.slice(1);
}

2. Confusão de delimitadores

O problema: Seu parser produz uma única coluna gigante em vez de múltiplos campos.

Por que acontece: Em muitas configurações regionais europeias e latino-americanas (França, Alemanha, Espanha, países da América Latina), o Excel usa ponto e vírgula (;) como delimitador de CSV porque as vírgulas são usadas como separadores decimais (por exemplo, 3,14 em vez de 3.14). Arquivos separados por tabulação (.tsv) adicionam outra variante.

A solução: Detectar automaticamente o delimitador amostrando as primeiras linhas:

import csv

with open('data.csv') as f:
    sample = f.read(8192)
    dialect = csv.Sniffer().sniff(sample, delimiters=',;\t|')
    f.seek(0)
    reader = csv.DictReader(f, dialect=dialect)

3. Zeros à esquerda desaparecem

O problema: O CEP 00501 se torna 501. O código de produto 007 se torna 7.

Por que acontece: O parser (ou o Excel) interpreta o campo como um número e remove os zeros à esquerda. Isso é especialmente perigoso com CEPs, números de telefone e códigos de identificação.

A solução: Forçar o tipo string. Em pandas:

df = pd.read_csv('data.csv', dtype={'zip': str, 'product_code': str})

Em JavaScript, verificar se a string original difere de sua conversão numérica:

function preserveLeadingZeros(value) {
  if (/^0\d+$/.test(value)) return value; // Manter como string
  const num = Number(value);
  return isNaN(num) ? value : num;
}

4. Perda de precisão em números grandes

O problema: O ID 9007199254740993 se torna 9007199254740992 no seu JSON.

Por que acontece: O tipo Number do JavaScript é um float de 64 bits (IEEE 754). Inteiros acima de Number.MAX_SAFE_INTEGER (2^53 - 1 = 9007199254740991) perdem precisão. Isso afeta IDs de bancos de dados, Snowflake IDs e IDs de posts do Twitter/X.

A solução: Manter números grandes como strings no JSON, ou usar BigInt no seu código de processamento:

// Parse com preservação de string para números grandes
function safeParseNumber(value) {
  const num = Number(value);
  if (Number.isInteger(num) && !Number.isSafeInteger(num)) {
    return value; // Manter como string para preservar precisão
  }
  return isNaN(num) ? value : num;
}

5. Ambiguidade de valores vazios

O problema: Seu CSV tem células vazias. Após a conversão, você não consegue saber se o valor original era uma string vazia "", null, ou simplesmente estava ausente.

Por que acontece: CSV não tem forma de distinguir entre esses três estados. Um campo vazio entre duas vírgulas (Alice,,30) poderia significar qualquer um deles.

A solução: Defina uma convenção e aplique-a de forma consistente:

def parse_value(value):
    if value == '':
        return None        # ou '' — escolha uma convenção
    if value == 'NULL' or value == 'null':
        return None
    return value

Se seus dados usam valores sentinela como NULL, N/A ou -, documente-os e trate-os explicitamente.

Streaming de arquivos grandes

Quando seu CSV ultrapassa 100 MB, carregá-lo completamente na memória não é uma opção. Use streaming.

Node.js (pipeline de streams):

import { createReadStream, createWriteStream } from 'fs';
import { parse } from 'csv-parse';
import { Transform } from 'stream';
import { pipeline } from 'stream/promises';

let first = true;
const toJsonArray = new Transform({
  objectMode: true,
  transform(record, encoding, callback) {
    const prefix = first ? '[\n' : ',\n';
    first = false;
    callback(null, prefix + JSON.stringify(record));
  },
  flush(callback) {
    callback(null, '\n]');
  }
});

await pipeline(
  createReadStream('large.csv'),
  parse({ columns: true, trim: true }),
  toJsonArray,
  createWriteStream('large.json')
);

Python (gerador):

import csv
import json

def csv_rows(path):
    with open(path, encoding='utf-8') as f:
        reader = csv.DictReader(f)
        for row in reader:
            yield row

# Stream para formato JSON Lines (um objeto JSON por linha)
with open('large.jsonl', 'w', encoding='utf-8') as out:
    for row in csv_rows('large.csv'):
        out.write(json.dumps(row, ensure_ascii=False) + '\n')

Para arquivos muito grandes, considere JSON Lines (.jsonl) em vez de um único array JSON. Cada linha é um objeto JSON independente, o que significa que você também pode processar o arquivo de saída linha por linha, sem necessidade de analisar todo o conteúdo.

Perguntas frequentes

Qual é a diferença entre CSV e JSON?

CSV (Comma-Separated Values) armazena dados como uma tabela plana onde cada valor é uma string de texto. JSON (JavaScript Object Notation) armazena dados estruturados com objetos aninhados, arrays e valores tipados (strings, números, booleanos, null). CSV é menor e amigável para planilhas; JSON é mais expressivo e amigável para APIs.

Como converto CSV para JSON em JavaScript?

Use o pacote csv-parse no Node.js: leia o arquivo com createReadStream, passe por parse({ columns: true }) e colete os resultados. Para uso no navegador, leia o arquivo com FileReader, divida por quebras de linha e mapeie as linhas para objetos usando a linha de cabeçalho como chaves.

Como converto CSV para JSON em Python?

Use csv.DictReader da biblioteca padrão para ler linhas como dicionários, depois json.dump() para escrevê-las como um array JSON. Para manipulação de dados antes da conversão, pandas.read_csv() seguido de df.to_json(orient='records') é uma alternativa de uma linha.

É possível converter JSON aninhado para CSV?

Sim, mas você precisa de uma estratégia de achatamento. A abordagem mais comum usa notação com pontos: um campo como address.city se torna um cabeçalho de coluna. Em Python, pandas.json_normalize() lida com isso automaticamente. Os arrays requerem decisões adicionais: unir como strings, expandir para colunas ou expandir para linhas.

Por que meu CSV tem caracteres ilegíveis após a conversão?

Incompatibilidade de codificação. O arquivo provavelmente foi salvo em Windows-1252 ou GBK, mas seu parser assume UTF-8. Use uma biblioteca de detecção como chardet (Python) para identificar a codificação, depois especifique-a explicitamente ao ler. Também verifique se há um BOM UTF-8 que algumas ferramentas adicionam automaticamente.

Como lido com um arquivo CSV de mais de 100 MB?

Use streaming em vez de carregar o arquivo completo na memória. No Node.js, passe por csv-parse com streams. Em Python, itere com csv.DictReader usando um gerador. Considere gerar formato JSON Lines (.jsonl) em vez de um único array JSON para facilitar o processamento posterior.

Como posso verificar que meu JSON convertido é válido?

Cole a saída em um JSON Formatter online para verificar sintaxe, estrutura e aninhamento. Para validação automatizada, use JSON.parse() em JavaScript ou json.loads() em Python — ambos lançam erros claros diante de entrada inválida. Para validação de esquema, defina um JSON Schema e valide programaticamente.

Conclusões principais

Escolha o método adequado para seu contexto: ferramentas no navegador para conversões pontuais, código para automação, CLI para pipelines.
Cuidado com problemas de codificação — sempre especifique a codificação explicitamente em vez de depender dos valores padrão.
Preserve os tipos intencionalmente — zeros à esquerda, inteiros grandes e valores nulos precisam de tratamento explícito.
Use streaming para arquivos grandes em vez de carregá-los na memória. Considere o formato JSON Lines para conjuntos de dados muito grandes.
Valide sua saída — passe o JSON convertido por um JSON Formatter para detectar problemas estruturais antes que cheguem à produção.

CSV para JSON: Métodos, erros comuns e exemplos de código