Passar dados de JSON para CSV parece uma simples troca de formato, mas implica escolher o que cabe numa tabela. JSON distingue números, texto, booleanos, valores null, propriedades ausentes e estruturas aninhadas. CSV organiza campos em registos e não inclui um sistema de tipos. Uma conversão útil precisa, por isso, de tornar visíveis as decisões que alteram o significado dos dados.
Neste guia, vamos exportar uma pequena lista sintética com o conversor de JSON para CSV. O exemplo contém identificadores com zeros iniciais, objetos, arrays, propriedades ausentes e texto semelhante a fórmulas. O objetivo é preparar uma entrega que outra pessoa consiga importar e verificar, sem presumir que uma folha de cálculo interpreta os campos da mesma forma que o sistema de origem.
Definir a tabela antes de a exportar
A entrada deve ser um array de objetos: cada objeto representa um registo e cada chave contribui para o conjunto de colunas. O conversor percorre os registos e acrescenta as chaves pela ordem em que aparecem pela primeira vez. Uma propriedade presente apenas no último objeto também aparece no cabeçalho. Não basta inspecionar a primeira linha para conhecer o esquema completo da exportação.
Quando uma propriedade falta, a respetiva célula fica vazia. Um valor null também produz uma célula vazia, tal como uma string vazia. Estas três situações deixam de ser distinguíveis. Se representam estados diferentes no teu processo, acrescenta previamente uma coluna de estado ou escolhe um formato que preserve a estrutura original.
Os objetos e arrays aninhados são serializados como texto JSON dentro de uma célula. Não são distribuídos por colunas com nomes inventados. Esta regra evita colisões entre caminhos, mas exige que o destinatário saiba se deve tratar a célula como texto ou voltar a analisá-la como JSON.
Experimentar com valores que revelam os riscos
Utiliza exatamente esta entrada sintética:
[
{
"id": "0012",
"name": "Ana",
"note": "=SUM(A1:A2)",
"profile": { "tier": "pro" },
"tags": ["docs", "qa"],
"active": true,
"score": null
},
{
"id": "0013",
"name": "Bela",
"note": "+441234",
"tags": [],
"active": false
}
]
Seleciona vírgula, desativa o BOM e mantém a proteção de fórmulas. O cabeçalho será id,name,note,profile,tags,active,score. O segundo registo terá a célula profile vazia, porque essa propriedade não existe. As duas células score estarão vazias, apesar de uma corresponder a null e a outra a uma propriedade ausente.
Os identificadores começam como strings. Contudo, o CSV não transporta uma declaração que obrigue uma folha de cálculo a respeitar esse tipo. O programa que abrir o ficheiro pode tentar transformar 0012 em número. Já os valores de profile e tags passam a conter texto JSON, incluindo o array vazio do segundo registo.
As duas notas recebem um apóstrofo inicial. Tanto =SUM(A1:A2) como +441234 começam por caracteres que podem desencadear interpretação como fórmula. O aviso da ferramenta indica que houve uma alteração deliberada do conteúdo.
Converter e verificar a entrega completa
Cola a entrada ou importa um ficheiro .json. Escolhe o delimitador que o destinatário espera: vírgula, ponto e vírgula ou tabulação. Esta escolha faz parte do contrato de importação. Não alteres o conteúdo para compensar um delimitador mal selecionado; confirma primeiro a configuração do programa que vai receber os dados.
Prime Converter e lê os avisos antes de descarregar. A pré-visualização mostra até 100 registos e 50 colunas, para manter a interface utilizável. A cópia e a transferência incluem o resultado completo dentro dos limites do motor. Uma tabela maior do que a área visível não significa que a exportação tenha sido cortada.
Abre primeiro o CSV num editor de texto. Confirma a ordem do cabeçalho, as aspas duplicadas nas células JSON e os apóstrofos das notas. Depois importa-o na folha de cálculo, indicando UTF-8 e o delimitador correto. Define a coluna dos identificadores como texto. Se o programa precisar de BOM para reconhecer os acentos, ativa essa opção e gera novamente o ficheiro.
Distinguir estrutura CSV de interpretação da folha
O RFC 8259 descreve os valores JSON; o RFC 4180 documenta uma convenção comum para registos CSV, separadores, aspas e quebras de linha. Nenhum deles define uma conversão universal entre os dois modelos. A ferramenta aplica regras explícitas: união estável das colunas, valores aninhados como texto JSON e células vazias para propriedades ausentes ou null.
As aspas CSV protegem a estrutura. Uma célula que contém o delimitador, aspas ou uma quebra de linha precisa de delimitação adequada. Uma aspa dentro de um campo delimitado aparece duplicada. Por isso, uma célula que contém {"tier":"pro"} pode parecer ter muitas aspas num editor. Removê-las manualmente pode destruir a separação dos campos.
A proteção de fórmulas atua noutra camada. Acrescenta um apóstrofo a texto que uma folha de cálculo poderia interpretar como expressão, incluindo cabeçalhos relevantes. Não calcula fórmulas nem garante o comportamento de todos os programas. A proteção modifica o valor; desativá-la exige uma decisão consciente quando o sistema de destino necessita do texto exato.
Corrigir problemas sem ocultar informação
Um erro que pede um array de objetos significa que a raiz não é um array ou que algum elemento é um valor primitivo, um array ou null. Envolve um objeto isolado num array apenas se ele representar realmente uma linha. Para conjuntos heterogéneos, define primeiro um esquema coerente em vez de inventar colunas durante a entrega.
O limite de entrada é 2 MiB em UTF-8 e 10.000 registos. Existe ainda uma proteção de um milhão de células na grelha de exportação. Muitos objetos pequenos com chaves diferentes podem gerar uma tabela enorme, mesmo quando o ficheiro original é curto. Reduz registos ou colunas de forma planeada; o conversor não devolve uma exportação parcial como se estivesse completa.
Se surgir um aviso sobre números fora do intervalo seguro, conserva esses valores como strings no JSON de origem. Depois de um número demasiado grande ser interpretado como número JavaScript, a precisão pode já ter sido perdida. Acrescentar aspas ao resultado arredondado não recupera os algarismos originais.
Documentar o que o destinatário deve esperar
Acompanha a exportação com o delimitador, a opção de BOM, o estado da proteção de fórmulas, a lista de colunas e a contagem de registos. Explica também o significado dos campos vazios e quais as colunas que contêm JSON serializado. Estes dados permitem repetir a importação sem depender de uma conversa ou de uma configuração pessoal guardada na folha de cálculo.
Considera a forma como a tabela será utilizada. Texto JSON numa célula pode ser adequado para outro programa, mas pouco prático para edição manual. Se houver necessidade de filtrar campos aninhados, prepara colunas explícitas ou uma tabela relacionada antes da conversão. Define nomes e regras de colisão para evitar que duas propriedades diferentes acabem com o mesmo nome.
O processamento ocorre no navegador e não exige enviar a entrada para um serviço. O ficheiro descarregado continua a ser uma nova cópia dos dados, sujeita às regras normais de armazenamento e acesso. O guia de privacidade das ferramentas de desenvolvimento ajuda a enquadrar esse processo.
Reconhecer o que não regressa ao JSON original
CSV não possui uma declaração universal de tipos, um marcador obrigatório para null nem uma representação nativa de objetos aninhados. Uma conversão bem-sucedida não garante que Excel, LibreOffice, uma base de dados e um importador próprio leiam tudo da mesma maneira. O programa de destino pode aplicar regras automáticas que a exportação não controla.
Ao voltar a importar, os booleanos podem surgir como texto, os objetos aninhados continuam a ser strings e as células vazias não revelam o estado original. O apóstrofo da proteção de fórmulas também faz parte do texto exportado. Consulta o guia de CSV para JSON para comparar os resultados com estas regras, em vez de exigir uma reversibilidade que o formato não oferece.
Para volumes superiores aos limites ou processos com requisitos rigorosos de auditoria, prepara uma rotina com esquema explícito, validação e testes no destino. Esta ferramenta resolve uma conversão local delimitada; não substitui o desenho de um processo de integração.
Confirmar o ficheiro antes de o partilhar
Verifica que a entrada contém apenas objetos e que conheces todas as colunas, incluindo as introduzidas por registos posteriores. Confirma os limites, o delimitador e a necessidade de BOM. Mantém a proteção de fórmulas ativa, salvo quando a conservação exata do texto tiver sido analisada para aquele destino.
No exemplo, exige dois registos, os identificadores 0012 e 0013, texto JSON completo em profile e tags, e um apóstrofo antes de cada nota. Regista que as células de score ficaram vazias por razões diferentes. Não uses apenas a pré-visualização para contar uma exportação extensa.
Por fim, importa o ficheiro descarregado com opções explícitas e compara os valores com o original. Confirma que o destinatário conhece as transformações e consegue repetir a operação. Guarda o JSON original quando for necessário investigar uma diferença; o CSV sozinho já não contém toda a informação de partida.
Fontes: RFC 8259: formato de intercâmbio JSON, RFC 4180: formato e tipo MIME de CSV e OWASP: CSV Injection.