Conversor de JSON para CSV

O que esta página faz e porque existe

Esta página converte ficheiros JSON em ficheiros CSV. O utilizador faz upload de um ficheiro JSON (ou arrasta-o para a zona indicada), escolhe um delimitador (vírgula, ponto e vírgula ou tabulação), pré-visualiza a tabela resultante e descarrega o ficheiro convertido. Todo o processamento acontece no navegador — nenhum dado é enviado para qualquer servidor.

O que distingue esta página de outras conversões (como CSV para Excel ou Excel para JSON) é que a direcção JSON→CSV achata um formato de dados hierárquico e tipado numa tabela plana e sem tipos. JSON suporta objectos, arrays, números, booleanos e null em estruturas aninhadas. CSV não tem tipos, não tem aninhamento nem múltiplas folhas. A conversão descarta toda a informação de tipo, a estrutura aninhada, as múltiplas folhas (que não existem em JSON) e qualquer formatação. Para representar objectos JSON aninhados numa tabela CSV, a ferramenta achata as chaves dos objectos usando notação de ponto (dot‑path), por exemplo address.city. Arrays de objectos transformam-se em linhas da tabela; arrays de arrays mantêm-se como linhas. Como o CSV usa delimitadores, as vírgulas e quebras de linha incorporadas nos valores têm de ser entre aspas — a ferramenta trata disso automaticamente, mas os zeros à esquerda em números podem perder-se. O utilizador deve decidir como os campos aninhados devem ser representados antes de converter (a ferramenta usa dot‑paths por omissão).

---

Como funciona a conversão de JSON para CSV

O processo é inteiramente do lado do cliente. Quando o utilizador carrega um ficheiro JSON, o código do navegador lê o conteúdo, verifica se o JSON é válido e se tem uma forma tabular. A ferramenta aceita apenas ficheiros JSON que sejam um array de objectos ou um array de arrays. Se o JSON for inválido ou não tiver essa forma, é apresentado o erro: “This JSON is invalid or not table‑shaped.”

Se o JSON for um array de objectos, cada objecto torna-se uma linha e as chaves do objecto tornam-se colunas. Chaves de objectos aninhados são achatadas com notação de ponto — por exemplo, um campo {"endereco": {"cidade": "Lisboa"}} transforma-se na coluna endereco.cidade. Se o JSON for um array de arrays, cada array interior torna-se uma linha e os elementos tornam-se colunas (não há chaves de objecto).

Após a conversão, é mostrada uma pré-visualização da tabela com a contagem de linhas e colunas e o tamanho do ficheiro de saída. O utilizador pode então descarregar o CSV.

Entradas e saídas

O ficheiro de entrada pode ter as extensões CSV, JSON ou XLSX — embora apenas o formato JSON seja relevante para esta página. A ferramenta rejeita ficheiros XLSX ou CSV se o utilizador esperar converter JSON, mas o campo de upload aceita esses formatos para facilitar arrastar ficheiros mistos. No entanto, a conversão só produzirá CSV a partir de JSON.

---

Diferenças estruturais entre JSON e CSV

JSON é um formato hierárquico e tipado. Um objecto JSON pode conter outros objectos, arrays, strings, números, booleanos e null. CSV é um formato tabular e não tipado: todas as células são strings, não existem hierarquias, e uma única tabela não pode representar directamente múltiplos níveis de aninhamento.

A conversão de JSON para CSV exige, portanto, uma perda de informação. O tipo original de cada valor é perdido: 42, true, null e "42" tornam-se todos strings “42”, “true”, “” (ou “null”) na saída CSV. Números com zeros à esquerda, como "00123", são interpretados como número e perdem os zeros, transformando-se em “123”. A estrutura aninhada, como um campo contacto.telefone dentro de um objecto, é achatada para uma única coluna com o nome contacto.telefone — perde-se a noção de que contacto era um objecto.

CSV também não suporta múltiplas folhas (sheets), ao contrário de ficheiros Excel. Como JSON não tem folhas, este problema não se coloca nesta direcção. A ausência de fórmulas ou formatação de células também é irrelevante: JSON não contém fórmulas, pelo que a conversão limita-se a valores visíveis.

Exemplo prático

JSON de entrada:

[
  {
    "nome": "Ana",
    "idade": 30,
    "endereco": {
      "cidade": "Porto",
      "codigo_postal": "4000-100"
    },
    "ativo": true,
    "notas": null
  }
]

CSV de saída (delimitador vírgula):

nome,idade,endereco.cidade,endereco.codigo_postal,ativo,notas
Ana,30,Porto,4000-100,true,

Note-se que true é convertido para a string “true” (sem aspas a não ser que contenha vírgulas ou quebras de linha), null torna-se uma célula vazia, e o codigo_postal mantém o zero à esquerda porque é uma string em JSON? Na verdade, 4000-100 é uma string porque contém hífen, por isso não perde zeros. Se fosse "00123", perderia os zeros. No exemplo acima, 4000-100 é string, portanto preservado.

---

O processo de flattening e a notação dot‑path

O achatamento (flattening) é a técnica central desta conversão. Quando um objecto JSON contém outro objecto como valor, as suas chaves são combinadas usando um ponto como separador. Este método é conhecido como dot‑path notation. Por exemplo:

{"a": {"b": 1, "c": 2}}

torna-se duas colunas: a.b e a.c.

O mesmo se aplica a arrays de objectos: se um valor for um array, o comportamento depende de como esse array é estruturado. A ferramenta trata arrays de objectos como sub‑tabelas? A descrição da página diz que arrays de objectos são mantidos como linhas — mas quando o array está dentro de um objecto, o flattening não o expande automaticamente em múltiplas linhas. Por exemplo:

[{"nome": "Ana", "telefones": [{"tipo": "casa", "numero": "123"}, {"tipo": "trabalho", "numero": "456"}]}]

Neste caso, telefones é um array de objectos. O flattening típico transformaria telefones numa única coluna com uma representação em string do array, ou expandiria em várias linhas? A página actual não expande arrays aninhados em múltiplas linhas. O array é convertido para uma string JSON dentro da célula CSV, ou é tratado como um erro? A ficha de factos diz que “arrays of objects become table rows; arrays of arrays are kept as rows”. Isto aplica-se ao nível raiz: se o JSON for um array de objectos, cada objecto é uma linha. Mas objectos aninhados com arrays dentro deles não são expandidos. Para evitar surpresas, a ferramenta exige que o JSON seja “table‑shaped” — tipicamente um único array de objectos planos ou de arrays planos, sem aninhamentos que compliquem.

Na prática, para a ferramenta funcionar correctamente, o JSON de entrada deve ser uma lista de objectos cujos campos são escalares ou objectos simples (que serão achatados). Arrays aninhados profundos ou estruturas irregulares podem levar ao erro “This JSON is invalid or not table‑shaped.”

Como decidir antes de converter

Antes de carregar o ficheiro, o utilizador deve verificar se o JSON tem uma forma tabular. Isso significa:

• O nível raiz é um array.
• Cada elemento do array é um objecto com as mesmas chaves (ou aproximadamente as mesmas).
• Valores aninhados são aceitáveis desde que sejam objectos (serão achatados) ou arrays planos (se todos os arrays tiverem o mesmo número de elementos, podem tornar-se linhas separadas? A ferramenta mantém arrays como linhas apenas quando o JSON é um array de arrays ao nível raiz. Dentro de objectos, arrays não são expandidos.)

Para JSON com arrays dentro de objectos, a conversão pode falhar ou produzir resultados inesperados. A melhor prática é transformar esses arrays em objectos planos antes de carregar o ficheiro, ou usar outra ferramenta de flattening.

---

Delimitadores e regras de citação CSV

O formato CSV é definido pela RFC 4180, embora existam variações. Os delimitadores mais comuns são a vírgula, o ponto e vírgula e a tabulação. A ferramenta permite escolher entre os três.

A escolha do delimitador afecta a forma como os valores são citados. Se um valor contiver o delimitador, uma quebra de linha ou uma aspa, o valor inteiro deve ser envolvido em aspas duplas, e qualquer aspa dentro do valor deve ser duplicada. Por exemplo, se o delimitador for vírgula e o valor for "Olá, mundo", o CSV escreve "Olá, mundo" (aspas à volta, vírgula dentro). Se o valor contiver aspas, como "Ele disse "Olá"", o CSV escreve "Ele disse ""Olá""" (aspas duplicadas).

A ferramenta aplica estas regras automaticamente. Contudo, o utilizador deve estar ciente de que, ao abrir o CSV num programa como o Excel ou o Google Sheets, o comportamento pode variar consoante a localidade. O Excel português, por exemplo, usa por omissão o ponto e vírgula como delimitador. Se o ficheiro for gerado com vírgulas, o Excel pode não reconhecer correctamente as colunas. Por isso, a ferramenta permite escolher o delimitador antes de descarregar.

Zeros à esquerda e tipagem

Um problema comum é a perda de zeros à esquerda em números. Em JSON, "00123" é uma string e mantém os zeros. Em CSV, se o valor for interpretado como número (por exemplo, ao abrir no Excel), os zeros desaparecem. A ferramenta produz o CSV com os zeros, mas o programa que lê o CSV pode ignorá‑los. Para evitar isso, o utilizador pode forçar a formatação de texto ao importar, ou usar um delimitador diferente e importar como texto. A ferramenta em si não altera o valor — apenas escreve a string tal como aparece no JSON. Se o JSON tiver 00123 como número (sem aspas), o valor é 123 e perde‑se o zero à esquerda. Se tiver "00123" como string, o zero é preservado na saída. A conversão de JSON para CSV não altera o tipo, mas o CSV final é sempre texto: o que importa é como o JSON representa o valor.

---

Limitações e casos extremos

A conversão não é possível em várias situações, e a ferramenta mostra mensagens de erro específicas:

Os limites exactos de tamanho de ficheiro e número de linhas/colunas não são especificados na ficha de factos, mas existem e são aplicados no código. A página não preserva fórmulas ou código (JSON não os tem). O processamento é exclusivamente do lado do cliente, o que garante privacidade — nenhum dado é enviado para servidores.

Quem precisa desta ferramenta

• Alguém que tenha um ficheiro JSON (por exemplo, de uma resposta de API) e precise dele em CSV para carregar no Excel, Google Sheets ou numa base de dados.
• Alguém que queira transformar dados JSON estruturados numa tabela plana para relatórios ou análise.
• Alguém que precise de converter dados sem os enviar para um servidor remoto (fluxos de trabalho sensíveis a privacidade).
• Alguém que precise de especificar um delimitador diferente (por exemplo, ponto e vírgula) para uma localidade não inglesa.
• Alguém que esteja a prototipar rapidamente pipelines de dados e precise de uma conversão JSON‑CSV rápida no navegador.

---

FAQ

P: O que acontece se o JSON tiver arrays dentro de objectos? R: A ferramenta não expande arrays aninhados em múltiplas linhas. O array pode ser convertido numa string JSON dentro da célula CSV, ou a conversão pode falhar se o JSON não for considerado tabular. É melhor preparar o JSON para que todos os valores sejam escalares ou objectos simples.

P: Perco tipos de dados ao converter? R: Sim. Todos os valores JSON (números, booleanos, null) são convertidos para strings no CSV. A ferramenta não preserva informação de tipo. Zeros à esquerda podem perder‑se se o valor JSON for um número em vez de uma string.

P: Como sei se o meu JSON é “table‑shaped”? R: Verifique se o nível raiz é um array e se cada elemento do array é um objecto com o mesmo conjunto de chaves (ou aproximadamente). Evite objectos com arrays de objectos ou estruturas profundamente aninhadas.

P: O ficheiro é enviado para um servidor? R: Não. Todo o processamento é feito no navegador. Nenhum dado sai do seu computador.

P: Posso converter um ficheiro XLSX ou CSV para CSV usando esta página? R: A página aceita esses formatos no upload, mas apenas converterá JSON para CSV. Se carregar um XLSX, provavelmente aparecerá o erro “Choose a CSV, JSON or XLSX file.” (aceita o formato mas depois tenta interpretar como JSON). A página não converte XLSX para CSV — para isso existe a página CSV‑to‑Excel ou Excel‑to‑CSV.

P: O que significa o erro “This conversion is taking too long. Try a smaller file.”? R: O processamento no navegador pode demorar para ficheiros muito grandes. A ferramenta interrompe a conversão após um certo tempo para evitar bloquear o navegador. Reduza o tamanho do ficheiro JSON ou simplifique a estrutura.