Artigo
Convertendo entre CSV, XML, JSON e YAML: um guia prático
CSV, JSON, XML e YAML são os quatro formatos que desenvolvedores encontram com mais frequência em pipelines de dados, arquivos de configuração e APIs. Converter entre eles é simples quando os modelos de dados coincidem, e surpreendentemente destrutivo quando não coincidem. Este guia explica o que cada formato pode e não pode representar, onde as informações desaparecem durante a conversão e as armadilhas de codificação que causam corrupção silenciosa. O data-converter deste site lida com três dos quatro formatos (CSV, JSON e YAML) inteiramente no navegador; as seções sobre XML aqui servem de referência para quando você mover dados manualmente ou com outra ferramenta.
Os quatro formatos e seus modelos de dados
CSV organiza dados em uma grade plana de linhas e colunas. A primeira linha geralmente nomeia as colunas; cada linha seguinte é um registro. Não há aninhamento, sem informação de tipo e nenhum padrão além de texto simples nas células. Cada valor é uma string, a menos que a aplicação consumidora imponha um tipo. JSON modela dados como uma árvore de objetos (mapas chave-valor) e arrays. Os valores podem ser strings, números, booleanos, null, objetos aninhados ou arrays de qualquer profundidade. Isso permite que um único documento JSON represente um registro de cliente com objetos de endereço incorporados, arrays de itens de linha e totais numéricos tipados. XML modela dados como uma árvore de elementos. Cada elemento pode conter atributos nomeados e incluir elementos filhos ou conteúdo de texto. Não existe tipo numérico ou booleano nativo; tudo é texto. Esquemas como XSD podem impor tipos na hora da validação, mas o formato de transmissão é sempre dado de caractere. YAML usa indentação para expressar o mesmo modelo de objetos e arrays do JSON, com sintaxe mais limpa e legível. YAML é um superconjunto de JSON: qualquer documento JSON válido também é YAML válido. Ele adiciona strings multilinhas, comentários e referências de âncora-alias para blocos repetidos. YAML é comum em arquivos de configuração; JSON é comum em respostas de API.
Conversões com perda: achatamento e a ambiguidade do XML
A conversão com perda mais comum é achatar JSON ou XML aninhado em CSV. Um objeto JSON com um campo de endereço aninhado não pode ser mapeado diretamente para uma linha CSV. A solução típica é usar nomes de colunas com notação de ponto: customer.address.city se torna sua própria coluna. Isso funciona para um nível de aninhamento, mas quebra completamente quando aparece um array. Um cliente com três números de telefone requer três colunas separadas (fixando o máximo), a divisão em um segundo arquivo CSV ou a codificação do array como uma string delimitada dentro de uma única célula. Nenhuma dessas opções permite retornar ao JSON original sem metadados extras. XML introduz uma ambiguidade adicional: a escolha entre atributo e elemento filho. O valor Paris pode ser armazenado como atributo (<city name="Paris">) ou como elemento filho (<city><name>Paris</name></city>). Quando um conversor lê XML e produz JSON, ele precisa decidir como mapear os atributos. As convenções comuns incluem prefixar as chaves de atributo com @ ou colocá-las sob uma chave "_attributes". A escolha não é padronizada, o que significa que dois conversores lendo o mesmo XML podem produzir JSON com estruturas diferentes. Se você planeja ir e voltar entre XML e JSON, defina uma convenção antes de começar.
Armadilhas do CSV: delimitadores, aspas e codificação
CSV não tem um único padrão formal, apenas a RFC 4180 como referência amplamente citada. O delimitador mais comum é a vírgula, mas ponto e vírgula (comuns em locales europeus onde vírgulas servem como separadores decimais), tabulações (TSV) e pipes também aparecem na prática. Um arquivo chamado .csv pode usar qualquer um deles sem indicar qual. Quando o valor de um campo contém o próprio delimitador, a RFC 4180 exige envolver o campo entre aspas duplas: "San Francisco, CA". Uma aspa dupla dentro de um campo entre aspas deve ser escapada dobrando-a: "He said ""hello""". Um campo contendo uma quebra de linha literal também deve ser colocado entre aspas. Analisadores que ignoram esse passo produzem erros de contagem de linhas difíceis de rastrear. A codificação é uma armadilha separada. Arquivos CSV de ferramentas Windows frequentemente carregam um BOM UTF-8 (byte order mark: os três bytes EF BB BF no início do arquivo). O BOM ajuda o Excel a identificar a codificação, mas muitos analisadores de linguagens de programação tratam o BOM como parte do primeiro nome de coluna, produzindo uma coluna chamada "\uFEFFid" em vez de "id". Isso quebra qualquer código downstream que busca colunas pelo nome. Ao ler um arquivo CSV programaticamente, remova o BOM antes de analisar ou use uma biblioteca que o trate explicitamente.
Escolhendo um formato: configuração, intercâmbio e planilhas
A escolha do formato geralmente é determinada pelo contexto, não pela preferência. JSON é o padrão para APIs REST e intercâmbio navegador-servidor. É compacto, analisado nativamente em todas as linguagens de programação e carrega informação de tipo para números e booleanos. Sua fraqueza é a ausência de comentários, o que o torna inadequado para arquivos que desenvolvedores leem e editam manualmente. YAML é preferido para arquivos de configuração (manifestos Kubernetes, definições de pipeline CI, playbooks Ansible) porque permite comentários inline e é mais fácil de ler do que JSON com muitos níveis de indentação. Seu principal risco é que erros de indentação são silenciosos: uma chave mal indentada muda de escopo sem nenhum erro de análise. XML permanece como padrão em sistemas empresariais mais antigos, serviços web SOAP, formatos de documento (DOCX, SVG, RSS) e contextos que exigem validação de esquema ou desambiguação de namespace. É verboso, mas o ferramental XPath e XSLT é maduro. CSV é a escolha certa quando os dados são genuinamente planos e o consumidor é um aplicativo de planilha ou um analista de dados. Não é adequado para configuração ou intercâmbio de API porque não tem sistema de tipos nem aninhamento.
Fazendo localmente com o data-converter
O data-converter neste site analisa e converte entre CSV, JSON e YAML inteiramente dentro do navegador; ele não lê nem grava XML. Nenhum dado é transmitido para um servidor em nenhum momento. A conversão é executada no seu ambiente JavaScript local, e a saída está disponível para download ou cópia sem que nada saia do seu dispositivo. Isso importa para dados que não são seus para compartilhar: respostas de API contendo informações pessoais, arquivos de configuração com nomes de host internos ou exportações CSV de bancos de dados internos. Colar esses dados em um conversor baseado na web que roda em um servidor significa que o conteúdo é enviado pela rede e processado em hardware que você não controla. Com o data-converter, a aba do navegador é o ambiente de processamento. A ferramenta aplica aspas RFC 4180 ao ler ou gravar CSV, e espera um array plano de objetos para converter JSON ou YAML em CSV: um valor de objeto ou array aninhado sob uma chave não recebe achatamento automático com notação de ponto, então achate esses campos você mesmo antes de converter se precisar deles como colunas separadas. Se você precisa mover dados de ou para XML, converta-os para JSON ou YAML com uma ferramenta XML dedicada primeiro e depois traga o resultado para cá.
Ferramentas neste artigo
Perguntas frequentes
Posso ir e voltar entre JSON e CSV e recuperar o original?
Somente se o JSON for um array plano de objetos sem campos aninhados e sem arrays como valores. No momento em que você tem um objeto aninhado ou um valor de array, a representação CSV requer uma decisão estrutural (colunas com notação de ponto, múltiplas linhas ou strings codificadas) que não pode ser revertida automaticamente. Se seus dados têm aninhamento, JSON, XML ou YAML fazem a ida e volta corretamente; CSV não faz.
Por que meu CSV parece errado no Excel após exportar de um aplicativo europeu?
Locales europeus geralmente usam ponto e vírgula como delimitador CSV porque as vírgulas são reservadas para notação decimal. O Excel em um locale europeu espera ponto e vírgula. Se o arquivo usar vírgulas, o Excel trata toda a linha como uma única coluna. A correção é alterar o delimitador nas configurações de exportação ou usar o assistente de importação de dados do Excel, que permite especificar o delimitador manualmente. O problema do BOM UTF-8 é separado: sem um BOM, o Excel pode interpretar mal os caracteres acentuados como texto distorcido.
Qual é a diferença entre YAML e JSON na prática?
Ambos representam o mesmo modelo de dados subjacente: objetos, arrays, strings, números, booleanos e null. YAML adiciona comentários (linhas começando com #), literais de string multilinhas e referências de âncora para blocos repetidos. JSON é estritamente um subconjunto de YAML válido, mas analisadores JSON não leem YAML. A regra prática: use JSON para payloads de API e armazenamento de dados; use YAML para arquivos de configuração que humanos editam e que se beneficiam de comentários inline.