Conversor de JSON para CSV

Por que a conversão JSON-para-CSV é um fluxo de trabalho tão comum

JSON é o formato de payload dominante em APIs web modernas; CSV é o formato de mínimo denominador comum para dados tabulares. Excel, Google Sheets, SQL LOAD DATA, R, Pandas, Tableau, Power BI e quase todo pipeline ETL ingerem CSV de fábrica. Então quando a saída de uma API precisa cair em uma planilha para alguém, ou em um banco de dados para análise, alguém tem que achatar o JSON em linhas. Esta ferramenta faz esse achatamento no seu navegador, sem ida e volta a servidor e sem upload de dados potencialmente sensíveis.

O formato CSV (RFC 4180)

Não existe um único padrão CSV formal, mas a RFC 4180 (outubro de 2005, «Common Format and MIME Type for Comma-Separated Values (CSV) Files») é o mais próximo de uma referência canônica que a indústria tem. As regras em que todos concordam:

• Um registro por linha, separado por quebras de linha. A RFC especifica CRLF; a maior parte dos parsers modernos aceita também LF.
• Os campos de um registro são separados por um único caractere delimitador, vírgula na forma canônica, mas ponto e vírgula, tab ou pipe são comuns em variantes regionais e legadas.
• Cada registro deve ter o mesmo número de campos. Valores faltantes viram células vazias; delimitadores extras são erro.
• Linha de cabeçalho é opcional; se houver, é a primeira linha.
• Campos que contêm vírgulas, quebras de linha ou aspas duplas devem ser delimitados por aspas duplas.
• Aspas duplas internas em um campo entre aspas são escapadas duplicando-as: "She said ""hello""".
• O tipo MIME registrado para CSV é text/csv.

Por que quatro delimitadores em vez de um

O padrão é vírgula, mas cada delimitador resolve um problema específico:

• Vírgula (,), padrão nos EUA, Reino Unido e outras locales anglófonas. Excel lê CSV com vírgula quando a configuração regional do SO é inglês. Padrão para application/csv no ecossistema de ferramentas em geral.
• Ponto e vírgula (;), padrão de fato na Europa continental, América Latina e outras regiões onde a vírgula é o separador decimal. Excel usa o separador de listas do SO, então um Excel em locale francês ou alemão produz CSV com ponto e vírgula.
• Tab, TSV (tab-separated values) é comum em dados científicos, bioinformática e em qualquer contexto em que os dados contenham vírgulas (texto livre, endereços).
• Pipe (|), preferido em alguns sistemas corporativos legados onde os dados podem conter vírgulas, ponto e vírgula E tabs. Raramente é a primeira escolha certa, mas útil quando nada mais resolve.

Achatar JSON aninhado: três estratégias

JSON é hierárquico; CSV é plano. Não há mapeamento de uso geral sem perdas entre os dois. Quando a entrada contém objetos ou arrays aninhados, todo conversor tem que escolher:

1. Inline como string JSON. A parte aninhada é reserializada em JSON e colocada em uma única célula CSV. Abordagem padrão desta ferramenta. Sem perdas; round-trip seguro; o consumidor precisa parsear o JSON interno se quiser a estrutura.
2. Achatamento com chaves pontuadas. {address: {street, city}} vira colunas address.street e address.city. O json_normalize do Pandas funciona assim. Mais limpo para analistas, mas a contagem de colunas explode em dados muito aninhados.
3. Explosão em linhas. Um array vira várias linhas, com os campos pai repetidos. {name: "Alice", tags: ["a", "b"]} vira duas linhas, ambas com name=Alice. Melhor para relações um-para-muitos; perde o modelo mental «um registro por linha».

Se precisar de saída com chaves pontuadas ou linhas explodidas, pré-processe o JSON antes de colar, seja com um pequeno script Python/Node ou com o json_normalize do Pandas.

Cabeçalhos, round-trip de tipos e a armadilha do auto-formato do Excel

JSON tem um sistema de tipos real (número, string, booleano, null, array, objeto); CSV tem apenas strings. A convenção é o consumidor inferir os tipos pelo contexto. A ferramenta gera cabeçalhos a partir da união de todas as chaves de todos os objetos de entrada, deixa campos ausentes como células vazias, escreve booleanos como true/false e escreve null do JSON como célula vazia.

O Excel é prestativo de formas que às vezes machucam:

• Remoção de zeros à esquerda. Uma coluna de CEPs como 01234 abre como o número 1234. Solução: prefixar com apóstrofo ('01234) dentro do CSV, ou usar o assistente de importação do Excel e definir explicitamente o tipo Texto.
• Conversão automática para datas. Strings que parecem datas (3/4/5, Mar-23) são convertidas em silêncio. Mesmas soluções.
• Notação científica. IDs numéricos longos (cartão de crédito, inteiros grandes) viram 1.23E+15 e perdem precisão. JSON preserva números até 2⁵³−1 exatamente; para maiores, transmita como string em JSON.
• Descompasso UTF-8 BOM. Excel no Windows usa Windows-1252 por padrão; abrir um CSV UTF-8 sem BOM corrompe caracteres não-ASCII (é, ü, å viram mojibake). Adicionar um BOM UTF-8 () no início do arquivo resolve. Google Sheets lida com UTF-8 sem BOM corretamente, então o BOM é específico de plataforma.

Injeção CSV, uma nota de segurança útil

Se um CSV vai ser aberto no Excel ou Google Sheets, uma célula que começa com =, +, - ou @ é interpretada como fórmula. A página de CSV Injection da OWASP documenta essa classe de ataque, uma string maliciosa como =cmd|' /c calc'!A0 em um campo enviado por usuário pode executar comandos quando um administrador abre o export. Prática defensiva: prefixe qualquer célula que comece com um desses quatro caracteres com aspa simples, ou envolva em aspas com apóstrofo inicial. Importante saber se você exporta conteúdo gerado por usuário.

Casos-limite comuns que o conversor trata

• Campo contendo o delimitador, entre aspas automaticamente. San Francisco, CA em CSV de vírgula vira "San Francisco, CA".
• Campo contendo uma quebra de linha literal, entre aspas; conteúdo multilinha é válido entre aspas pela RFC 4180.
• Campo contendo aspas duplas, entre aspas, com as aspas internas duplicadas: She said "yes" vira "She said ""yes""".
• Arrays e objetos vazios, serializados respectivamente como [] e {} nas células.
• Registros com chaves diferentes, a união de todas as chaves forma a linha de cabeçalho; campos faltantes são células vazias.
• Objeto único vs array, um único objeto JSON vira CSV de uma só linha.

Quando usar esta ferramenta

• Exportar respostas de API para interlocutores que querem uma planilha para ordenar e filtrar.
• Importação em massa de JSON para um banco SQL via LOAD DATA INFILE (MySQL) ou COPY (PostgreSQL). Ambos esperam entrada em formato CSV.
• Análise rápida em Excel, Google Sheets, Pandas, R, Tableau ou Power BI.
• Gerar listas de e-mails a partir de uma resposta JSON de API de contatos.
• Migrar dados entre sistemas que não compartilham API mas ambos falam CSV.
• Revisar um arquivo JSON a olho quando ele é repetitivo demais para ser lido direto, a visão em planilha costuma ajudar.

Privacidade

Exports CSV quase sempre contêm PII, registros de clientes, dados de funcionários, logs de transações, listas de contatos. A conversão em servidor envia cada registro pela infraestrutura de terceiros, onde ele vive em logs de trânsito, logs de servidor e possivelmente em caches. A conversão baseada em navegador mantém os dados na sua máquina. Todo o passo de achatar e escapar acontece aqui em JavaScript dentro do seu navegador; nada é enviado.

Erros comuns

1. Delimitador errado para o público. Enviar CSV com vírgula a um usuário de Excel francês produz arquivo de uma coluna só. Combine o delimitador com a locale do destinatário.
2. Colar um objeto único em vez de um array. Um único objeto vira CSV de uma linha com cabeçalhos a partir das chaves. Para vários registros, embrulhe em um array.
3. Esperar achatamento estilo Pandas. Objetos aninhados nesta ferramenta são serializados como strings JSON dentro das células. Se quiser colunas address.street, achate antes.
4. Usar CSV para números muito grandes. JSON representa com segurança inteiros até 2⁵³−1 (~9 quadrillions em escala curta). Acima disso, transmita como string. O Excel destrói IDs numéricos longos mesmo quando o CSV os preserva.
5. Abrir no Excel sem pensar em codificação. Caracteres não-ASCII precisam de BOM UTF-8 para Excel no Windows; Google Sheets e o Excel moderno na web não precisam.
6. Exportar texto de usuário sem higienizar prefixos de fórmula. Células que começam com =, +, - ou @ são fórmulas no Excel e Sheets. A injeção CSV é um ataque real contra administradores que abrem arquivos exportados.

Perguntas frequentes

Meu JSON tem objetos aninhados. Como são tratados?

Cada objeto ou array aninhado é serializado como string JSON dentro da sua célula CSV. Então {user: {name: "Alice", role: "admin"}} vira uma coluna chamada user contendo {"name":"Alice","role":"admin"}. Round-trip sem perdas. Se precisar de user.name e user.role separados, pré-processe com json_normalize do Pandas ou um pequeno script de achatamento.

Por que meus caracteres não ingleses ficam estranhos no Excel?

Excel no Windows abre CSV em Windows-1252 por padrão. CSV UTF-8 sem Byte Order Mark fica como mojibake (é → é). Solução: salvar o arquivo com BOM UTF-8, usar o assistente Dados → Do texto do Excel e selecionar explicitamente UTF-8, ou abrir o arquivo no Google Sheets, que lida com UTF-8 sem BOM corretamente.

A ferramenta trata vírgulas dentro de campos?

Sim. Pela RFC 4180, campos que contêm o delimitador, quebras de linha ou aspas duplas são automaticamente delimitados por aspas duplas. As aspas internas são escapadas dobrando-as. Então San Francisco, CA vira "San Francisco, CA" e She said "hi" vira "She said ""hi""".

Meu JSON é enviado a um servidor?

Não. A conversão roda inteiramente no seu navegador. O conteúdo do textarea não é transmitido, registrado nem armazenado em lugar nenhum. Isso importa porque registros exportados frequentemente contêm PII, dados de clientes, info de funcionários, históricos de transações, que você não quer trafegando pela infraestrutura de outra pessoa.

Posso obter saída separada por tabulações (TSV)?

Sim, escolha «Tab» no dropdown de delimitador. TSV é a escolha certa quando seus dados contêm vírgulas (endereços, texto livre, dados financeiros com separadores de milhar) e você não quer envolver uma célula sim, outra não em aspas. Muitos formatos de bioinformática e dados científicos são TSV por padrão.

Qual é o limite de tamanho?

O que seu navegador aguentar. Não há limite de servidor porque não há servidor envolvido. Dezenas de megabytes de JSON convertem em um ou dois segundos em um dispositivo moderno; payloads de centenas de megabytes começam a ficar lentos. Para datasets muito grandes, particione em lotes ou mude para um conversor em streaming na linha de comando.

Ferramentas relacionadas