Um engenheiro DevOps exporta uma configuração Kubernetes como YAML, mas precisa enviá-la para uma API que só aceita JSON. Um analista recebe dados de resposta de API em JSON, mas precisa deles em uma planilha. Um cientista de dados exporta um CSV de um banco de dados, mas precisa de JSON estruturado para um painel web.
A conversão de formatos não é apenas uma operação mecânica. Cada formato faz compromissos diferentes, e entender o que se perde na tradução é tão importante quanto saber como converter.
Três formatos, três filosofias
Cada formato foi projetado para um público e um problema diferente:
| Formato | Nascimento | Projetado para | Filosofia central |
|---|---|---|---|
| CSV | ~1972 | Troca de dados entre programas | Máxima simplicidade — apenas linhas e colunas |
| JSON | 2001 | Intercâmbio de dados web | Dados estruturados legíveis por máquina com regras rígidas |
| YAML | 2001 | Arquivos de configuração | Dados estruturados legíveis por humanos com sintaxe mínima |
CSV assume que seus dados são uma tabela plana. Cada valor é uma string. Não existe conceito de aninhamento, tipagem ou metadados.
JSON assume que seus dados têm estrutura — objetos, arrays, tipos (strings, números, booleanos, null). É estrito e inequívoco, o que o torna ideal para máquinas, mas verboso para humanos.
YAML assume que um humano vai ler e editar o arquivo. Usa indentação em vez de chaves, suporta comentários e tem uma sintaxe mais relaxada. Tecnicamente, YAML é um superconjunto de JSON — qualquer documento JSON válido também é YAML válido.
YAML é um superconjunto de JSON Você pode colar um documento JSON diretamente em um parser YAML e vai funcionar. O inverso não é verdade — recursos do YAML como comentários, âncoras e strings multilinha não têm equivalente em JSON.
Cenários reais de conversão
Migração de configuração (JSON para YAML, YAML para JSON)
Esta é a conversão mais comum. Diferentes ferramentas esperam diferentes formatos de configuração:
- Docker Compose, Kubernetes, GitHub Actions, Ansible usam YAML
- package.json, tsconfig.json, ESLint usam JSON
- Migrar entre ferramentas frequentemente significa converter configurações
Esta conversão é sem perda em ambas as direções para o conteúdo de dados — mas os comentários YAML se perdem ao converter para JSON, já que JSON não tem sintaxe de comentários.
Análise de dados (JSON para CSV)
Respostas de API vêm em JSON. Analistas precisam de planilhas. Esta conversão funciona bem para arrays JSON planos — arrays de objetos com chaves idênticas mapeiam naturalmente para linhas e colunas.
Mas falha com dados aninhados. Um objeto JSON com um campo address.city e um array skills não tem representação CSV natural. O conversor deve escolher: achatar chaves aninhadas (address.city vira uma coluna), serializar valores aninhados como strings ou descartá-los.
Importação de dados (CSV para JSON)
O cenário inverso: importar dados de planilha em uma aplicação web ou API. A conversão CSV para JSON cria um array de objetos, com os cabeçalhos das colunas como chaves. O problema é que CSV não tem informação de tipos — o número 42, a string "42" e o booleano true são todos apenas texto em CSV. O conversor precisa adivinhar os tipos.
Legibilidade humana (JSON para YAML)
Às vezes você só precisa tornar um arquivo de configuração JSON denso mais legível. Converter para YAML oferece indentação limpa e a possibilidade de adicionar comentários para documentação. Isso é especialmente valioso para arquivos de configuração grandes que serão mantidos por uma equipe.
O que se perde na conversão
Este é o conhecimento crítico que economiza tempo de depuração:
| Conversão | O que se perde |
|---|---|
| YAML para JSON | Comentários (JSON não tem sintaxe de comentários) |
| JSON para CSV | Aninhamento (CSV é plano), tipos (tudo vira texto), arrays |
| CSV para JSON | Nada (mas tipos precisam ser inferidos — "42" vs 42) |
| CSV para YAML | Nada (mesmo problema de inferência de tipos) |
| JSON para YAML | Nada (YAML é um superconjunto de JSON) |
| YAML para CSV | Comentários, aninhamento, tipos, âncoras/aliases |
O padrão é claro: conversões em direção ao CSV perdem mais informação, porque CSV é o formato mais simples. Conversões entre JSON e YAML são quase sem perda. E os comentários YAML são sempre perdidos ao sair do YAML.
Bidirecional vs. unidirecional JSON-para-YAML e YAML-para-JSON são efetivamente bidirecionais (ida e volta segura, exceto pelos comentários). JSON-para-CSV e YAML-para-CSV são unidirecionais para dados complexos — não é possível reconstruir aninhamento a partir de um CSV plano.
Armadilhas comuns ao converter
As ciladas de coerção de tipos do YAML
YAML interpreta automaticamente certas strings como tipos não-string. A palavra no se torna booleano false. A palavra yes se torna true. A string 1.0 se torna um float. Códigos de país como NO (Noruega) já causaram bugs famosos. Sempre coloque entre aspas os valores ambíguos no YAML.
Confusão com delimitadores e codificação CSV
Nem todos os CSVs usam vírgulas. CSVs europeus frequentemente usam ponto e vírgula (porque vírgulas são separadores decimais em muitos formatos numéricos europeus). Valores separados por tabulação (TSV) são outra variante. E incompatibilidades de codificação de caracteres (UTF-8 vs Latin-1) produzem caracteres acentuados ilegíveis.
O problema da vírgula final no JSON
JSON não permite vírgulas finais. Isto é JavaScript válido: {"a": 1, "b": 2,} — mas é JSON inválido. Uma única vírgula final causa um erro de parsing.
Desempenho com grandes conjuntos de dados
Para conjuntos de dados com milhões de linhas, CSV é significativamente mais eficiente que JSON ou YAML. JSON adiciona chaves, colchetes e aspas para cada valor. Um CSV com 1 milhão de linhas pode ter 50 MB; o JSON equivalente pode ter 150 MB.
Escolher o formato certo desde o início
Em vez de converter depois, escolher o formato certo desde o início evita perda de informação:
- Dados tabulares para planilhas ou bancos de dados — CSV
- Dados estruturados para APIs ou aplicações web — JSON
- Configuração que humanos vão editar — YAML
- Dados aninhados complexos com comentários — YAML
- Intercâmbio de dados entre sistemas — JSON
Para ir além
Converta entre JSON, YAML e CSV instantaneamente com ferramentas baseadas no navegador:
- Converter formatos de dados — cole seus dados, escolha o formato alvo, baixe o resultado
- JSON Formatter — validar, formatar e minificar JSON
- Conversor JSON para CSV — converter arrays JSON em CSV pronto para planilhas
- Conversor YAML-JSON — converter entre YAML e JSON com reconhecimento de comentários