O que é CSV? Entendendo os valores separados por vírgula

O CSV é o formato de dados mais antigo e mais simples que ainda é amplamente usado hoje. Ele é décadas mais antigo que o JSON, é mais antigo que o XML e sobreviveu a inúmeras alternativas "melhores". O motivo é óbvio: é apenas texto com vírgulas. Qualquer aplicativo de planilha consegue abri-lo, qualquer linguagem de programação consegue interpretá-lo e qualquer pessoa consegue lê-lo se precisar.

Mas a simplicidade vem com suas peculiaridades. O CSV não tem um padrão oficial que todos sigam, não tem uma forma nativa de representar dados aninhados e tem alguns casos extremos relacionados a aspas que confundem as pessoas com frequência. Este guia cobre o que você precisa saber.

Como o CSV se parece

Na sua forma mais simples, um arquivo CSV é composto por linhas de valores separados por vírgulas, com cada linha em uma linha própria:

name,age,city
Alice,30,Tokyo
Bob,25,London
Charlie,35,New York

A primeira linha normalmente é uma linha de cabeçalho que nomeia cada coluna. As demais linhas são os dados. Esse é o formato inteiro.

Se você já exportou dados do Excel, do Google Sheets, de um banco de dados ou de uma ferramenta de análise, provavelmente já gerou um arquivo CSV. É o formato universal de menor denominador comum para dados tabulares.

A linha de cabeçalho

A linha de cabeçalho é uma convenção, não uma exigência. Não há nada no próprio formato CSV que diga que a primeira linha precisa conter os nomes das colunas. Mas, na prática, quase todo arquivo CSV que você encontrar terá uma.

product_id,product_name,price,in_stock
1001,Widget A,9.99,true
1002,Widget B,14.50,true
1003,Widget C,7.25,false

Quando um programa lê esse arquivo, ele usa a linha de cabeçalho para associar cada valor ao nome da sua coluna. Sem o cabeçalho, você teria apenas uma grade de valores sem rótulos, e o código que consome os dados precisaria saber a ordem das colunas de antemão.

Regras de aspas

É aqui que o CSV fica interessante. O que acontece quando um valor em si contém uma vírgula?

name,description,price
"Deluxe Widget","Large, heavy-duty model",29.99

Você envolve o valor em aspas duplas. As aspas dizem ao parser que a vírgula dentro de "Large, heavy-duty model" faz parte do valor, e não é um separador de campo.

E quanto a valores que contêm aspas duplas?

Você as escapa duplicando o caractere de aspas:

name,quote
"Alice","She said ""hello"" to Bob"

O valor interpretado do segundo campo é: She said "hello" to Bob

E quanto a quebras de linha dentro de um valor?

Também são tratadas com aspas:

name,address
"Alice","123 Main St
Apartment 4B
Tokyo"

O campo de endereço abrange três linhas, mas as aspas duplas o mantêm como um único valor. Isso é CSV válido, embora nem todo parser o trate corretamente.

A regra geral

Um campo precisa estar entre aspas se contiver:

Uma vírgula
Aspas duplas
Um caractere de quebra de linha

Alguns geradores de CSV colocam todos os campos entre aspas, independentemente do conteúdo, o que é seguro, mas produz arquivos um pouco maiores. Outros só usam aspas nos campos que realmente precisam.

Delimitadores e variantes

Apesar do nome "valores separados por vírgula" (Comma-Separated Values), nem todos os arquivos CSV usam vírgulas. Variantes comuns incluem:

TSV (Tab-Separated Values) — usa tabulações no lugar de vírgulas. Comum em bioinformática e em algumas exportações de bancos de dados.
Separado por ponto e vírgula — comum em países europeus onde a vírgula é usada como separador decimal. Se você abrir um CSV de uma instalação alemã do Excel, pode encontrar pontos e vírgulas.
Separado por barra vertical — usa | como delimitador. Menos comum, mas aparece em sistemas legados.

A maioria dos parsers de CSV permite que você especifique o delimitador, então as diferenças costumam ser fáceis de lidar. O termo "CSV" é usado de forma genérica com frequência para se referir a todas essas variantes.

O que o CSV não consegue fazer

Entender as limitações do CSV ajuda você a saber quando usar um formato diferente.

Sem tipos de dados

Todo valor em um arquivo CSV é uma string. O número 42, o booleano true e o texto "hello" são todos apenas sequências de caracteres. A aplicação que consome os dados decide como interpretá-los.

Isso significa que:

007 pode perder os zeros à esquerda se uma planilha o interpretar como número
true e false são apenas strings, a menos que o leitor as converta
Datas como 2026-03-20 não têm uma representação padrão — é 20 de março ou o vigésimo mês? Depende da localidade e do leitor.

Sem aninhamento

O CSV é plano. Você não consegue representar uma lista de itens dentro de uma única célula, nem um objeto com subpropriedades. Se os seus dados têm uma estrutura hierárquica, o CSV obriga você a achatá-la.

Por exemplo, um usuário com múltiplos endereços de e-mail não se encaixa naturalmente no CSV:

name,email
Alice,alice@work.com
Alice,alice@personal.com

Você acaba duplicando a linha ou amontoando vários valores em um único campo com algum separador improvisado, como um ponto e vírgula. Nenhuma das abordagens é elegante. O JSON lida com isso naturalmente por meio de arrays, o que é uma das razões pelas quais as pessoas convertem CSV para JSON quando os dados precisam de mais estrutura. Para uma introdução de como o JSON trata esses casos, veja O que é JSON.

Sem metadados

O CSV não tem como incluir metadados, como informações de codificação, definições de schema ou números de versão. Se você precisa saber qual codificação de caracteres um arquivo CSV usa (UTF-8? Latin-1? Shift-JIS?), tem que adivinhar ou verificar por fora.

Sem especificação padrão (mais ou menos)

A RFC 4180 descreve um formato comum para CSV, mas é uma RFC informativa, não um padrão. Ferramentas diferentes produzem CSV ligeiramente diferentes, e os parsers precisam ser flexíveis. A boa notícia é que as variações costumam ser pequenas.

CSV e planilhas

O CSV é a ponte entre as planilhas e todo o resto. Quase todo aplicativo de planilha oferece suporte à importação e exportação de CSV:

Excel: Arquivo > Salvar como > CSV
Google Sheets: Arquivo > Fazer download > Valores separados por vírgula
LibreOffice Calc: O mesmo padrão

Isso torna o CSV o formato ideal quando você precisa tirar dados de uma planilha e levá-los para um programa, ou quando um membro não técnico da equipe precisa fornecer dados em um formato que o código consiga consumir.

O fluxo de trabalho normalmente é assim:

Alguém mantém os dados em uma planilha
Essa pessoa os exporta como CSV
Um programa lê o CSV e o converte para o formato que a aplicação precisar

A etapa 3 muitas vezes significa converter para JSON, especialmente se os dados forem consumidos por uma aplicação web ou uma API.

Quando converter CSV para JSON

Existem vários cenários práticos em que converter CSV para JSON faz sentido.

Integração com APIs

Se você tem dados em uma planilha que precisam ser enviados para uma API REST, a API quase certamente espera JSON. Converter a exportação CSV para JSON é a ponte óbvia.

Configuração e dados estruturados

Quando dados tabulares planos precisam se tornar estruturados — por exemplo, transformar uma lista plana de produtos com colunas de categoria em uma estrutura JSON aninhada agrupada por categoria — a conversão é o primeiro passo.

Aplicações de frontend

Aplicações web e mobile trabalham com JSON nativamente por meio do JavaScript. Carregar um CSV em uma aplicação de frontend exige uma etapa de parsing, enquanto o JSON pode ser usado diretamente.

Análise de dados

Ferramentas como notebooks Jupyter e pipelines de dados às vezes aceitam JSON com mais facilidade que CSV, especialmente quando os dados têm tipos mistos ou campos opcionais.

Convertendo CSV para JSON

A conversão de CSV para JSON é conceitualmente simples: cada linha vira um objeto JSON, com os valores do cabeçalho como chaves.

Partindo deste CSV:

name,age,city
Alice,30,Tokyo
Bob,25,London

Você obtém este JSON:

[
  {
    "name": "Alice",
    "age": "30",
    "city": "Tokyo"
  },
  {
    "name": "Bob",
    "age": "25",
    "city": "London"
  }
]

Repare que age continua sendo uma string ("30", não 30). Como o CSV não tem informação de tipo, o conversor não sabe se 30 deve ser um número ou uma string. Alguns conversores oferecem opções para inferir tipos, mas o padrão geralmente é tratar tudo como strings.

Você pode fazer essa conversão na hora com a ferramenta CSV para JSON. Cole o seu CSV e receba o JSON de volta. Para um passo a passo detalhado, incluindo o tratamento de casos extremos, veja Como converter CSV para JSON.

Dicas para trabalhar com CSV

Sempre verifique a codificação

Se você ver caracteres ilegíveis depois de abrir um arquivo CSV, quase certamente é um problema de codificação. Tente abrir o arquivo como UTF-8. Se isso não funcionar, o arquivo pode estar em uma codificação legada, como Shift-JIS (comum em arquivos CSV japoneses) ou Latin-1.

Cuidado com a formatação automática do Excel

O Excel adora "ajudar" convertendo coisas que se parecem com números ou datas. Um código de produto como 001234 vira 1234. Um valor como 1-2 vira uma data. Se você está trabalhando com dados CSV que serão abertos no Excel, fique atento ao fato de que os dados podem ser modificados silenciosamente.

Use um parser de verdade

Escrever o seu próprio parser de CSV dividindo o texto nas vírgulas é tentador, mas frágil. Ele quebra com campos entre aspas, quebras de linha nos valores e aspas escapadas. Use uma biblioteca — toda linguagem tem uma. O Python tem o módulo csv, o JavaScript tem o PapaParse, e assim por diante.

Valide antes de processar

Se você recebe arquivos CSV de fontes externas, valide-os antes de presumir que a estrutura está correta. Verifique se o número de colunas é consistente entre as linhas, se os cabeçalhos esperados estão presentes e se os campos obrigatórios não estão vazios.

Experimente agora

Tem um arquivo CSV que você precisa em formato JSON? Cole-o no conversor de CSV para JSON e obtenha uma saída JSON estruturada na hora. Sem cadastro, sem upload de arquivo — tudo roda no seu navegador.

Conclusão

O CSV sobreviveu por décadas porque faz uma coisa bem: representar dados tabulares da maneira mais simples possível. Ele não vai a lugar nenhum. Mas quando os seus dados ultrapassam as tabelas planas — quando você precisa de aninhamento, tipos ou estrutura — converter para JSON costuma ser a decisão certa.

Entender ambos os formatos e quando alternar entre eles é uma habilidade prática que surge com frequência em trabalhos com dados, desenvolvimento web e integração de sistemas.