CSV para JSON
Última atualização: 1 de outubro de 2026
Leia uma tabela CSV de volta como array de objetos JSON. A linha de cabeçalho dá as chaves, na leitura as regras de aspas da RFC 4180 são entendidas e a detecção de tipos você decide se ativa. Tudo acontece no navegador: a tabela não sai da máquina.
O que a conversão faz
O CSV carrega os nomes das colunas na primeira linha, então a conversão é um mapeamento direto: as células do cabeçalho viram nomes de propriedade e cada linha seguinte vira um objeto no array. A tabela
id,name
1,Ada
2,Gracevira [{"id":"1","name":"Ada"},{"id":"2","name":"Grace"}]. Repare que os valores são strings: é o comportamento padrão, e o motivo está na seção seguinte.
A linha de cabeçalho é o esquema
A primeira linha é tomada como cabeçalho, não como dado. Dois casos-limite são tratados em vez de ficarem como surpresa:
- Nomes duplicados: um cabeçalho repetido se torna único, então
a,apassa a seraea_2. Sem isso, a segunda coluna sobrescreveria a primeira em silêncio. - Nomes vazios: uma célula de cabeçalho em branco recebe nome pela posição,
column 1,column 2, e assim por diante, para que nenhuma chave seja uma string vazia.
A detecção de tipos fica desativada por padrão, de propósito
O CSV não tem tipos. Cada célula é texto, e o arquivo não consegue distinguir um número de um código que por acaso tem dígitos. Por isso a detecção é opcional: desativada, todos os valores continuam strings, que é a leitura fiel do arquivo.
Ao ativá-la, só o inequívoco é convertido. Um valor é tratado como número quando poderia ser escrito como um número JSON —sinal de menos opcional, dígitos, parte decimal opcional e expoente opcional—, e true, false e null são reconhecidos como tais. O ponto crucial é que um valor com zero à esquerda não é convertido, porque 007 e 02139 quase sempre são identificadores: CEPs, telefones, números de conta, códigos de produto. Um «transforme tudo em número» às cegas viraria 007 em 7 e corromperia os dados; esta regra não.
Campos entre aspas, vírgulas internas e quebras de linha
A leitura segue a RFC 4180, a mesma regra com que a página de JSON para CSV escreve. Um campo entre aspas duplas pode conter o delimitador, uma quebra de linha ou um par de aspas duplas que volta a ser uma só. Assim, "Ada, Countess" é um único valor que contém uma vírgula, e um valor que ocupa duas linhas físicas continua uma célula. Aceitam-se tanto CRLF quanto LF, e uma marca de ordem de bytes UTF-8 inicial——o U+FEFF invisível que o Excel e alguns exportadores adicionam——é removida, para que o primeiro nome de coluna não saia como id.
Linhas de comprimento irregular
Arquivos editados à mão raramente são um retângulo limpo. Uma linha com menos campos que o cabeçalho é preenchida com valores vazios e uma com mais é cortada, de modo que todos os objetos ficam com as mesmas chaves. A alternativa —rejeitar o arquivo inteiro— é menos útil do que devolver as linhas bem formadas, mas implica que os valores que faltam realmente não estão lá.
Perguntas frequentes
Como o CSV se mapeia para objetos JSON?
A primeira linha é lida como cabeçalho e suas células viram nomes de propriedade; cada linha seguinte vira um objeto no array, com esses nomes como chaves. Um CSV com o cabeçalho id,name e uma linha 1,Ada produz [{ "id": "1", "name": "Ada" }].
Por que meus números e booleanos saem como strings?
A detecção de tipos fica desativada por padrão, e isso é de propósito. O CSV não tem tipos, então o conversor não pode saber se 007 é o número sete ou o código zero-zero-sete; um palpite errado corrompe em silêncio identificadores como CEPs, telefones e números de conta. Ative a detecção quando souber que a coluna é numérica e, mesmo assim, um valor com zero à esquerda continua string.
O que exatamente conta como número quando a detecção está ativada?
Somente texto que poderia ser escrito como um número JSON: um sinal de menos opcional, dígitos sem zero à esquerda exceto quando o valor é exatamente 0, uma parte decimal opcional e um expoente opcional. true, false e null também são reconhecidos. Todo o resto, incluindo 007 e 1,234, continua string.
Como campos entre aspas, vírgulas internas e quebras de linha são lidos?
A análise segue a RFC 4180: um campo entre aspas duplas pode conter o delimitador, uma quebra de linha ou uma aspa dupla duplicada, que volta a ser uma só. Assim, uma célula com Ada, Countess é escrita "Ada, Countess" e um valor em duas linhas continua um único campo. Aceitam-se tanto CRLF quanto LF.
Meu arquivo tem BOM UTF-8; o primeiro nome de coluna vai quebrar?
Não. A marca de ordem de bytes inicial——o U+FEFF invisível que algumas ferramentas, o Excel entre elas, colocam no início de um CSV——é removida antes da análise, senão o primeiro cabeçalho seria lido como id. Aqui ele é lido como id.
O que acontece com linhas que não batem com o cabeçalho?
Uma linha com menos campos que o cabeçalho é preenchida com valores vazios, e uma com mais é cortada, de modo que todos os objetos têm as mesmas chaves. Linhas irregulares são comuns em arquivos editados à mão e são toleradas em vez de rejeitadas, mas os dados que faltam realmente não aparecem na saída.
Quer a direção contrária? JSON para CSV escreve um array de objetos como tabela. Encontrou um bug? Fale conosco.