Converter CSV em JSON

Onde o CSV é mais vago do que parece

O CSV não tem um padrão de verdade — há uma especificação consultiva de 2005 que descreve o que a maioria das ferramentas faz, e muito software que faz outra coisa. Então o primeiro trabalho é descobrir o que o arquivo realmente é: se os valores são separados por vírgulas, ponto e vírgula ou tabulações (localidades europeias exportam com ponto e vírgula, porque a vírgula é o separador decimal delas), se a primeira linha é um cabeçalho e como as aspas são tratadas. Um campo entre aspas pode conter, legalmente, vírgulas, quebras de linha e aspas duplicadas, e é por isso que dividir nas vírgulas é o jeito errado de ler um CSV e por que um parser ingênuo corrompe qualquer arquivo que contenha um endereço.

Os tipos são o segundo trabalho, e o JSON tem opiniões que o CSV não tem. Uma célula de CSV contém texto e nada mais; o JSON distingue números, strings, booleanos e null. Algo precisa decidir o que é o quê, e as decisões que importam são as que dão errado: um zero à esquerda é significativo em um CEP, um número de telefone ou um número de conta, então um valor como 01234 precisa continuar string em vez de virar o número 1234. O mesmo vale para identificadores longos, que perdem precisão como números JSON acima de uns nove quatrilhões.

As datas ficam como o texto que eram, porque o JSON não tem tipo de data. 2024-03-05 sai como a string "2024-03-05", e essa é a resposta honesta, não uma limitação — a alternativa é adivinhar, e adivinhar é como 03/05/2024 vira março em um país e maio em outro. Convertê-las é uma decisão de quem consome o JSON, que sabe o formato que quer.

A codificação é a última falha silenciosa. Um CSV não traz nenhuma indicação da sua codificação de caracteres, então um arquivo salvo como Windows-1252 e lido como UTF-8 gera caracteres embaralhados exatamente nas linhas com nomes acentuados — e uma marca de ordem de bytes no início, que o Excel adiciona, aparece como caracteres estranhos no primeiro nome de campo se não for tratada. As duas coisas são características do CSV, não de um conversor específico.

Quando você precisa de outra coisa

Para arquivos grandes demais para caber na memória, ou para qualquer coisa automatizada por script, o csvkit foi feito para isso: csvjson --stream data.csv converte aos poucos, csvlook permite ver primeiro o que você tem, e csvclean conserta as linhas irregulares que quebram tudo depois. O Miller — mlr --icsv --ojson cat data.csv — faz o mesmo com bastante velocidade e lida com JSON delimitado por linhas, que é o que a maioria dos pipelines de dados realmente quer.

Quando os tipos importam mais do que a conveniência, faça a conversão em código, com os tipos declarados em vez de inferidos. O pandas do Python com um mapeamento dtype explícito, ou um pequeno script com um esquema, garante que um CEP continue sendo CEP e que um identificador mantenha todos os dígitos — o que nenhuma inferência automática consegue garantir em um arquivo que ela não viu por inteiro.