Tutorial de CSV para JSON: conversão estruturada de dados tabulares

Por que converter CSV para JSON

CSV é um formato de dados tabulares, o formato padrão exportado pelo Excel. JSON é um formato amigável para programas, o padrão para transmissão de API. Converter CSV para JSON permite que dados tabulares sejam consumidos diretamente por programas.

Cenários comuns:

• Importar dados do Excel para o banco de dados de um site
• Conectar dados tabulares a uma API
• Repassar resultados de análise de dados para o front-end renderizar
• Migrar configurações de planilha para arquivos JSON

Diferenças entre CSV e JSON

Formato CSV

name,age,city
Tom,25,Lisboa
Jerry,30,Porto

• Texto puro, separado por vírgulas
• A primeira linha é o cabeçalho
• Cada linha é um registro
• Sem tipos (tudo é string)
• Sem estrutura aninhada

Formato JSON

[
  {"name": "Tom", "age": 25, "city": "Lisboa"},
  {"name": "Jerry", "age": 30, "city": "Porto"}
]

• Estruturado, pares chave-valor
• Com tipos (string, número, booleano)
• Suporta aninhamento
• Analisável diretamente por programas

Princípio da conversão

Mapeamento de cabeçalho

A primeira linha do CSV é o cabeçalho; ao converter para JSON, o cabeçalho vira as chaves do objeto:

• Cabeçalho: name, age, city
• Primeira linha de dados: Tom, 25, Lisboa
• Conversão: {"name": "Tom", "age": "25", "city": "Lisboa"}

Reconhecimento de tipo de dados

Todos os valores em CSV são strings. Ao converter para JSON, pode-se reconhecer o tipo de forma inteligente:

• Número: "25" → 25 (número)
• Booleano: "true" → true (booleano)
• Nulo: "" → null (nulo)
• String: permanece string

Se não reconhecer o tipo, trata tudo como string.

Geração de array

Cada linha do CSV vira um objeto; todas as linhas formam um array:

[
  {objeto1},
  {objeto2}
]

Estrutura aninhada

O problema

CSV é uma tabela plana; JSON suporta aninhamento. Como converter CSV plano em JSON aninhado?

Método 1: nomes de chave com ponto

Use pontos no cabeçalho do CSV para indicar a hierarquia:

name,address.city,address.zip
Tom,Lisboa,1000-001

Converter para JSON:

{
  "name": "Tom",
  "address": {
    "city": "Lisboa",
    "zip": "1000-001"
  }
}

Método 2: índice de array

name,tags[0],tags[1]
Tom,A,B

Converter para JSON:

{
  "name": "Tom",
  "tags": ["A", "B"]
}

Método 3: separação por ponto e vírgula

name,tags
Tom,"A;B;C"

Converter para JSON:

{
  "name": "Tom",
  "tags": ["A", "B", "C"]
}

Etapas da conversão

1. Preparar o CSV

Garanta que o CSV esteja no formato correto:

• A primeira linha é o cabeçalho
• Campos separados por vírgulas
• Campos com vírgula devem ser envolvidos por aspas duplas
• Campos com aspas duplas devem usar duas aspas duplas como escape

2. Enviar ou colar

Cole o conteúdo do CSV na ferramenta de conversão ou envie o arquivo CSV.

3. Configurar opções

• Se reconhecer tipos de dados
• Como tratar a estrutura aninhada
• Formato de saída (array ou objeto linha a linha)

4. Converter

A ferramenta converte automaticamente e gera o JSON.

5. Validar

Verifique se o resultado JSON atende ao esperado:

• Os campos estão corretos
• Os tipos estão corretos
• O aninhamento está correto

Problemas comuns

Campos com vírgula

Campos CSV com vírgula devem ser envolvidos por aspas duplas:

name,desc
Tom,"Hello, world"

Se não envolver, serão tratados como dois campos e a conversão falhará.

Caracteres ilegíveis

Use codificação UTF-8 no CSV. O Excel pode usar GBK por padrão; ao exportar, escolha UTF-8.

Tratamento de valores vazios

Células vazias no CSV viram string vazia "" ou null no JSON?

• Padrão: string vazia ""
• Reconhecimento inteligente: null
• Depende da opção da ferramenta

Precisão de números

Números muito grandes podem perder precisão ao converter para JSON. Por exemplo, um número de identidade de 18 dígitos vira notação científica como número. Trate números de identidade como string (adicione um prefixo de aspas no CSV ou especifique o tipo string na conversão).

Formato de data

O formato de data no CSV não é uniforme (2024-01-01, 2024/1/1, Jan 1 2024). Ao converter para JSON, mantenha como string e analise no front-end.

Cabeçalho BOM

CSVs exportados pelo Excel podem conter um cabeçalho BOM (\uFEFF), resultando em um caractere invisível antes do primeiro nome de campo. A ferramenta de conversão deve remover o BOM automaticamente.

Dicas de conversão

Pré-processar o CSV

Antes de converter, organize no Excel:

• Exclua linhas vazias
• Padronize o formato de data
• Verifique a integridade dos campos

Conversão seletiva

Converta apenas as colunas necessárias. Exclua no CSV as colunas que não precisa para reduzir o tamanho do JSON.

Conversão em lotes

CSVs muito grandes podem travar em uma única conversão. Converta em lotes de algumas centenas de linhas.

Validação do resultado

Após converter, embelezze com uma ferramenta de formatação JSON e verifique manualmente alguns registros para confirmar a correção.

Converter com o DocsAll

Ferramenta CSV para JSON:

1. Envie um arquivo CSV ou cole o conteúdo CSV
2. A ferramenta analisa automaticamente o cabeçalho e os dados
3. Configure as opções de conversão (reconhecimento de tipos, etc.)
4. Gere o JSON
5. Copie ou baixe o resultado

Conversão no navegador, os dados CSV não são enviados ao servidor, adequado para dados sensíveis.

Conversão inversa: JSON para CSV

Às vezes é necessário o caminho inverso, converter JSON para CSV:

• A API retorna JSON e você quer exportar para Excel para análise
• Exportar campos JSON de um banco de dados para uma planilha

Dificuldades do JSON para CSV:

• Estruturas aninhadas precisam ser achatadas
• Tratamento de campos de array (concatenar ou expandir em várias linhas)
• Preencher valores vazios quando os campos não são uniformes

Resumo

O núcleo da conversão de CSV para JSON é o mapeamento do cabeçalho para nomes de chave, o reconhecimento de tipos de dados e o tratamento de estruturas aninhadas. Atenção a campos com vírgula, codificação de caracteres, valores vazios e precisão de números grandes. A ferramenta CSV para JSON do DocsAll roda no navegador, sem enviar dados para fora.