Uma tabela CSV pode perder significado antes de chegar a uma aplicação: um código postal perde zeros, um número longo é arredondado ou uma quebra de linha divide um campo em dois registos. Estes problemas não se resolvem apenas produzindo JSON válido. É necessário compreender a estrutura do CSV e decidir separadamente se o texto de cada célula deve mudar de tipo.
Vamos utilizar o conversor de CSV para JSON com um exemplo pequeno e repetível. Contém uma vírgula dentro de um nome, uma nota com duas linhas, uma célula vazia, identificadores com zeros iniciais e um inteiro demasiado grande para conversão numérica segura. A comparação entre inferência desativada e ativada mostra exatamente o que muda e o que deve permanecer intacto.
Separar a leitura do ficheiro da escolha de tipos
Analisar CSV significa descobrir onde começa e acaba cada campo e registo, respeitando delimitadores e aspas. Inferir tipos significa decidir se o texto encontrado representa um número ou um booleano. Quando um programa faz as duas coisas de forma invisível, é difícil saber se um resultado errado veio da estrutura do ficheiro ou de uma interpretação posterior.
Por predefinição, o conversor preserva strings. O campo 0012 torna-se "0012", true torna-se "true" e uma célula vazia torna-se "". Esta escolha evita atribuir significados que o CSV não declara. Uma coluna com aspeto numérico pode conter códigos de conta ou referências de fatura, e não quantidades.
A inferência é opcional e conservadora. Converte booleanos exatos e formas numéricas seguras; conserva zeros iniciais e inteiros fora do intervalo seguro como texto. Não identifica datas, unidades, moedas ou regras de negócio. Ativá-la deve ser uma decisão apoiada pelo esquema do destinatário.
Preparar uma amostra que deteta erros frequentes
Cria um ficheiro UTF-8 com este conteúdo exato:
id,name,note,amount,enabled
0012,"Doe, Ana","Line one
Line two",9007199254740993,true
0013,Bela,,12.5,false
Existem dois registos de dados, apesar de a nota ocupar duas linhas físicas. As aspas mantêm Line one e Line two dentro da mesma célula. A vírgula de Doe, Ana também pertence ao nome, não cria outra coluna. No segundo registo, os dois delimitadores seguidos representam a nota vazia.
Com inferência desativada, todas as propriedades resultantes são strings. A primeira nota contém uma quebra de linha real; no JSON serializado, essa quebra aparece escapada. Os dois valores de amount e os dois de enabled também permanecem entre aspas. O cabeçalho fornece cinco nomes de propriedade para cada objeto.
Ao ativar a inferência, apenas 12.5, true e false mudam para os tipos correspondentes. Os identificadores conservam os zeros e 9007199254740993 continua a ser string. Converter esse inteiro para um número JavaScript poderia alterar os algarismos, pelo que preservá-lo como texto é parte do comportamento esperado.
Importar por etapas verificáveis
Abre a ferramenta e seleciona vírgula. Cola a amostra ou importa um ficheiro .csv, .tsv ou .txt com a mesma estrutura. O BOM UTF-8 de entrada é aceite e não passa a fazer parte do primeiro nome de propriedade. Se a origem usa ponto e vírgula ou tabulação, escolhe esse delimitador antes de modificar os dados.
Converte primeiro sem inferência. Confirma dois objetos, cinco propriedades por objeto e a nota multilinha intacta. Copia ou descarrega o JSON e verifica-o com um analisador independente quando o resultado fizer parte de um processo automatizado. Um teste externo ajuda a distinguir o conteúdo real de uma representação visual da interface.
Ativa depois a inferência e volta a converter. Compara apenas as alterações previstas, sem aceitar diferenças adicionais por parecerem plausíveis. Para ficheiros maiores, a pré-visualização mostra até 100 registos e 50 colunas, mas o resultado descarregado é completo. Confirma o comprimento do array exportado, não o número de linhas visíveis na página.
Interpretar corretamente cabeçalhos, aspas e números
O RFC 4180 descreve uma convenção comum de CSV: campos separados por vírgulas, aspas que protegem conteúdo especial e aspas internas duplicadas. Ficheiros reais podem utilizar outros delimitadores. Um ficheiro tabulado lido como CSV de vírgulas pode parecer ter apenas uma coluna enorme, sem produzir necessariamente um erro de sintaxe esclarecedor.
O primeiro registo fornece as chaves JSON. Cada cabeçalho precisa de ser não vazio e único; caso contrário, duas colunas poderiam competir pela mesma propriedade. Os registos seguintes devem ter exatamente o mesmo número de células. O conversor rejeita diferenças e indica o registo lógico afetado, contando a própria linha de cabeçalho.
Os números exigem outra cautela. JavaScript representa números com precisão limitada, e Number.isSafeInteger identifica inteiros que podem ser representados e comparados sem ambiguidade. JSON permite escrever um inteiro longo, mas isso não obriga todos os leitores a preservá-lo numericamente. Conservar os algarismos numa string permite que o sistema de destino escolha posteriormente um tipo adequado, como um inteiro arbitrário ou um decimal de base de dados.
Corrigir o registo de origem em vez de esconder o erro
Se houver uma cabeçalho duplicado, altera os nomes de forma significativa no esquema de origem. Evita acrescentar números aleatórios apenas para ultrapassar a validação. Um cabeçalho vazio também precisa de um nome real. Depois de corrigir, verifica se as aplicações que consomem as chaves conhecem esses nomes.
Um erro de contagem de colunas pode resultar de uma vírgula sem aspas, uma aspa não fechada ou uma quebra de linha fora da célula pretendida. Analisa o registo indicado e a célula anterior que abriu aspas. A numeração conta registos lógicos desde um, incluindo o cabeçalho. Uma linha física não corresponde sempre a um registo CSV, sobretudo na presença de notas multilinha. Não elimines pontuação ao acaso para fazer o erro desaparecer.
A entrada está limitada a 2 MiB UTF-8 e 10.000 registos. A saída JSON também possui uma proteção estimada de 16 MiB: cabeçalhos muito longos repetem-se em cada objeto e podem ampliar bastante um CSV pequeno. Reduz registos, colunas ou comprimento dos nomes quando necessário. Divide ficheiros apenas entre registos completos, repetindo o cabeçalho em cada parte.
Preservar o significado dos identificadores e vazios
Decide os tipos com base num contrato de dados. Um código 1234 pode precisar de continuar a ser string mesmo sem zeros iniciais. Números de telefone, códigos postais, referências internas e números de documento são exemplos em que a aparência numérica não implica uma operação aritmética. Quando o texto exato importa, deixa a inferência desligada e transforma propriedades específicas num passo posterior.
Uma célula vazia não fornece provas de que o valor seja null. Pode significar desconhecido, não aplicável, ainda não preenchido ou simplesmente texto vazio. Se o sistema de origem define um marcador como NULL, documenta uma transformação separada. O mesmo vale para datas: 2026-09-17 não indica por si só um fuso horário nem o tipo temporal esperado.
A conversão é local, mas o JSON descarregado é uma nova cópia do conjunto de dados. Aplica as regras habituais de acesso e retenção. Para investigar problemas de sintaxe posteriores, consulta o guia de erros JSON e utiliza exemplos sintéticos em relatórios ou capturas de ecrã.
Não confundir JSON válido com dados corretos
O importador reconhece o delimitador escolhido e a estrutura CSV. Não descobre relações entre ficheiros, unidades, formatos monetários, separadores decimais regionais ou campos obrigatórios. A inferência não substitui um esquema e não transforma automaticamente datas em objetos temporais. Um campo com vírgula decimal pode continuar a ser texto mesmo que o destinatário espere um número.
Um array JSON sintaticamente correto também pode conter valores inadequados para a aplicação. O conversor não verifica unicidade de identificadores, intervalos numéricos, permissões ou dependências entre propriedades. Para dados que vão entrar num sistema de produção, utiliza validação de esquema ou uma área de importação onde as regras de negócio possam ser verificadas.
Se precisares de voltar a CSV, segue o guia de JSON para CSV. A passagem inversa aplica regras próprias para valores aninhados, campos vazios e proteção de fórmulas. Uma sequência de duas conversões não deve ser tratada como prova automática de conservação integral.
Conferir a importação antes de a integrar
Regista a codificação, o delimitador, os nomes das colunas e a contagem de registos na origem. Confirma que os cabeçalhos são únicos e que cada registo tem o número correto de campos. Converte primeiro sem inferência para estabelecer uma referência em que o texto original permanece visível.
Na amostra, exige exatamente dois objetos. Mantém 0012, 0013 e 9007199254740993 como strings. Confirma a quebra de linha na primeira nota e a string vazia na segunda. Ao ativar a inferência, aceita a mudança de 12.5 para número e de true e false para booleanos, sem outras alterações inesperadas.
Descarrega o resultado completo, volta a analisá-lo e compara a quantidade de objetos com a fonte. Valida então os tipos e as regras exigidas pelo destinatário. Guarda as opções utilizadas junto do procedimento, para que a próxima importação seja repetível e não dependa de configurações escolhidas de memória.
Fontes: RFC 4180: formato e tipo MIME de CSV, RFC 8259: formato de intercâmbio JSON e ECMAScript: Number.isSafeInteger.