Como converter CSV para JSON sem perder metade dos seus dados

Um CSV vira JSON quando cada linha se transforma em um objeto e cada cabeçalho de coluna vira uma chave, então um arquivo que começa com id,name,city sai como um array de objetos com essas três propriedades. Qualquer conversor faz isso, inclusive o deste site, que analisa o texto no seu navegador e devolve o array. O trabalho está nas divergências entre os dois formatos: o CSV não tem tipos, nem aninhamento, nem declaração de codificação, e o JSON precisa das três coisas resolvidas antes de escrever um único caractere.

Como a saída fica de verdade

Com este CSV:

id,name,city,joined
1,Ada,London,1843-01-01
2,Grace,New York,1944-07-02

o JSON é um array de dois objetos:

[
  { "id": 1, "name": "Ada", "city": "London", "joined": "1843-01-01" },
  { "id": 2, "name": "Grace", "city": "New York", "joined": "1944-07-02" }
]

Esse formato — um array de objetos planos com chaves vindas da linha de cabeçalho — é o que a maioria das APIs, dos importadores de banco de dados e das bibliotecas JavaScript espera. Nenhum conversor consegue saber se a sua primeira linha é dado ou cabeçalho, então, se o arquivo não tem linha de cabeçalho, você precisa avisar; as chaves passam a ser nomes posicionais como column_1. Nada consegue inventar nomes com sentido para colunas que ninguém rotulou.

Por que você não pode simplesmente separar pelas vírgulas

O primeiro leitor de CSV que qualquer pessoa escreve é um split por vírgulas dentro de um loop sobre as linhas. Funciona no arquivo de exemplo e depois corrompe em silêncio o de verdade, porque três características do formato o quebram.

Campos entre aspas. "Lovelace, Ada" é um único valor. Separe pela vírgula e você obtém dois, e todas as colunas à direita dele se deslocam uma posição só naquela linha — que é o pior tipo de bug, porque o arquivo continua carregando.

Aspas duplicadas. Dentro de um campo entre aspas, uma aspa dupla literal é escrita duas vezes. "She said ""no""" é um único valor: She said "no". No CSV não existe escape com barra invertida; se você presumiu que existia, está corrompendo qualquer coisa que contenha um símbolo de polegada.

Quebras de linha dentro dos campos. Um campo entre aspas pode conter quebras de linha, o que significa que uma linha de CSV e uma linha de texto não são a mesma coisa. Ler o arquivo linha a linha já é o bug, antes de você ter feito qualquer parse.

Essas regras vêm da RFC 4180, o memorando de 2005 que colocou no papel o que todo mundo já fazia. Ela é informativa e não obrigatória, e é por isso que arquivos reais fogem dela: retornos de carro soltos, ponto e vírgula como delimitador, linhas em branco no final. Um parser que vale a pena tolera tudo isso e ainda acerta as três regras, o que exige uma máquina de estados caractere a caractere em vez de uma expressão regular.

Por que o seu CSV inteiro sai como uma única linha

Uma única aspa dupla sem par arruína tudo o que vem depois. A partir daquele caractere, o parser acredita que está dentro de um campo entre aspas, então vírgulas e quebras de linha deixam de ser separadores e viram texto comum. As linhas anteriores à aspa solta sobrevivem; o resto do arquivo desaba em uma única linha com um único valor enorme.

O culpado de sempre é um símbolo de polegada solto, uma altura escrita como 5"11 ou uma medida como 24" wide que nunca foi escapada. Nenhuma ferramenta consegue adivinhar onde a aspa deveria ter fechado: procure na entrada uma " sozinha e corrija ali. Se um conversor relata muito menos linhas do que você colou, é a primeira coisa a verificar.

Por que zeros à esquerda e IDs longos somem

Todo campo de um CSV é texto. O JSON distingue 42 de "42", então o conversor precisa decidir, campo a campo, e cada decisão errada é perda silenciosa de dados. As vítimas clássicas:

• Zeros à esquerda. O CEP 01234 vira 1234. O código de produto 007 vira 7.
• Zeros à direita. O preço 1.50 vira 1.5, o que importa no instante em que ele é impresso de volta em uma nota fiscal.
• Números de telefone. +44 é lido como o número 44 e o sinal de mais some.
• Identificadores longos. Na prática, os números do JSON são doubles IEEE 754, então acima de 9007199254740991 não dá mais para confiar que um inteiro sobreviva exato: ele volta com os últimos dígitos trocados. Números de cartão, snowflake IDs e referências de pedido de 19 dígitos caem todos aqui.

Existe uma regra segura, e ela é estreita: converta um campo para número só se imprimir esse número devolver exatamente os caracteres originais. 42 passa no teste. 007, 1.50, +44, 1e3 e todo inteiro grande demais falham e continuam strings. É essa a regra que o conversor daqui usa. Ela traz dois efeitos colaterais que vale conhecer antes de você comparar a saída: true e false viram booleanos, e uma célula vazia vira null em vez de uma string vazia. Se algum dos dois importa, desligue a conversão de tipos e faça o cast das colunas você mesmo depois: com ela desligada, cada célula que existe no arquivo sai como o texto exato que continha.

As datas continuam strings, e essa é a resposta certa

O JSON não tem tipo de data. 03/04/2024 é 3 de abril na maior parte do mundo e 4 de março nos Estados Unidos, e nada no arquivo diz qual dos dois. Um conversor que escolhe um está adivinhando por você, e vai errar em uma parte das suas linhas sem falar nada. Mantenha as datas como strings ISO-8601 — 2024-04-03 — e deixe quem consome o JSON decidir o que elas significam.

O que acontece com as linhas que não batem com o cabeçalho

Exportações reais têm linhas irregulares. O tratamento sensato é mantê-las em vez de rejeitar o arquivo: uma linha curta recebe null nas colunas que faltam, e uma longa guarda as sobras sob chaves posicionais. O que importa é o conversor dizer que isso aconteceu. Linhas irregulares quase sempre significam que o arquivo está danificado — um delimitador solto, um download truncado —, então uma contagem de quantas ficaram curtas ou longas é um diagnóstico, não uma nota de rodapé.

Dá para tirar JSON aninhado de um CSV plano?

Não só a partir do arquivo, e esse é o limite que faz as pessoas procurarem uma opção que não existe. Um CSV é um retângulo. Se a sua coluna se chama address.city, uma conversão direta devolve uma chave com um ponto no nome, e não um objeto address contendo um city. O ponto significa algo para você e nada para o arquivo.

Alguns conversores oferecem ler nomes com ponto como caminhos. Isso é uma convenção, não um formato, e quebra na primeira vez que um nome de coluna legítimo contém um ponto. Se você precisa de saída aninhada, converta para JSON plano e remodele em algumas linhas de código, em vez de torcer para que uma caixinha tenha adivinhado o seu schema.

Por que caracteres acentuados chegam como lixo

Se José aparece como José, o estrago aconteceu antes da conversão. São bytes UTF-8 lidos como Latin-1, e isso ficou gravado quando o arquivo foi salvo ou aberto. A correção é reexportar como UTF-8 a partir da fonte original. Ir no sentido contrário — decodificar o texto estragado de volta — às vezes funciona, mas qualquer caractere que a code page errada não conseguiu representar já foi substituído por um ponto de interrogação ou um marcador, e nenhuma quantidade de redecodificação traz esses de volta. Comece pelo arquivo original, se você ainda o tiver.

Um detalhe relacionado: a exportação "CSV UTF-8" do Excel escreve um byte order mark no início do arquivo. A menos que algo o remova, esse caractere invisível gruda no nome da sua primeira coluna, e você passa vinte minutos se perguntando por que data[0].id é undefined quando a chave é, na verdade, \uFEFFid. O conversor daqui remove um BOM inicial antes do parse, então esse não chega à sua saída — mas um script que você mesmo escrever não vai fazer isso a menos que você peça. Qualquer coisa que estrague o texto de um jeito que você não consegue ver vale a pena conhecer em geral, e o mesmo tipo de problema aparece quando um e comercial nos seus dados encontra o HTML e sai do outro lado como &.

O que uma ida e volta perde em cada direção

Converter JSON de volta para CSV achata tudo: objetos aninhados são colapsados em colunas com ponto, um array é espremido em uma única célula como texto JSON, e todo tipo vira texto de novo. Então uma ida e volta CSV → JSON → CSV não vai devolver um arquivo idêntico byte a byte, e uma ida e volta JSON → CSV → JSON perde os tipos de vez. Se você precisa do caminho inverso, o conversor de JSON para CSV cuida do achatamento, e o que uma estrutura aninhada custa na descida vale a leitura antes de você adotar isso como etapa de um pipeline.

Quando parar de usar um conversor e escrever código

Uma ferramenta de navegador é a escolha certa para um arquivo pontual, uma amostra que você precisa olhar, ou um texto colado de uma planilha. Ela deixa de ser certa em três pontos: arquivos acima de alguns megabytes, porque tudo fica na memória — o seletor de arquivos daqui recusa qualquer coisa acima de 5 MB em vez de travar a sua aba, embora nada impeça você de colar essa quantidade de texto na mão —; qualquer coisa que você vá fazer mais de duas vezes, porque um script que dá para reexecutar ganha de uma aba que você precisa lembrar; e qualquer coisa que exija streaming, em que as linhas são processadas conforme chegam.

Fora isso, a verificação é sempre a mesma. Converta e depois leia o primeiro objeto e o último. Zeros à esquerda intactos, datas ainda como strings, nenhuma chave com um caractere estranho, contagem de linhas batendo com a planilha. Trinta segundos, e isso pega quase todas as falhas listadas aqui.

Última atualização 19 de setembro de 2026