JSON vs YAML vs CSV: Qual Formato de Dados Você Deve Usar?

Se você desenvolve software há mais de alguns anos, quase certamente já digitou cada um desses três formatos em um arquivo em algum momento. JSON jorra de cada endpoint REST. YAML é a língua franca dos manifests do Kubernetes, dos workflows do GitHub Actions e de metade das CLIs que você instala. CSV é o que o marketing te envia por e-mail quando quer "os dados brutos". Eles parecem intercambiáveis, e ferramentas como o Multilities tornam a conversão entre eles trivial, mas o fato de que você pode converter não significa que você deva escolher aleatoriamente.

Este artigo passa por como cada formato realmente funciona, onde brilha, onde quebra e as regras de bolso que equipes experientes usam para escolher um. Vamos olhar o mesmo conjunto de dados renderizado de três formas para que as compensações sejam concretas em vez de abstratas.

Um modelo mental rápido

Antes de se afogar na sintaxe, segure os formatos na cabeça assim:

• JSON é um formato de serialização para objetos estruturados. É o que você usa quando uma máquina precisa falar com outra máquina e humanos só ocasionalmente leem a saída.
• YAML é um quase-superset do JSON otimizado para humanos editando arquivos de configuração à mão. Ele assume que uma pessoa vai rolar, comparar (diff) e revisar.
• CSV é um formato tabular. Ele assume que toda linha tem o mesmo formato, e que o consumidor é provavelmente uma planilha, um comando COPY de banco de dados ou uma chamada rápida pandas read_csv.

JSON: o padrão para APIs e JS

JSON, JavaScript Object Notation, foi extraído do JavaScript no início dos anos 2000 e padronizado como RFC 8259. Ele tem seis tipos primitivos: object, array, string, number, boolean e null. Esse é todo o vocabulário. Não há datas, nem comentários, nem vírgulas finais, nem referências. O minimalismo é o ponto: qualquer linguagem pode parsear JSON em algumas centenas de linhas de código, razão pela qual toda API HTTP do planeta eventualmente acaba nele.

Navegadores parseiam JSON nativamente com JSON.parse, toda stdlib de backend tem um módulo JSON, e variantes amigáveis a binário como MessagePack e CBOR existem quando você supera a representação textual. Para payloads de request/response, envio de logs, estado JS persistido e bancos de dados de documentos, JSON é quase sempre o padrão correto.

YAML: o ponto ideal de configuração

YAML, originalmente Yet Another Markup Language e mais tarde recursivamente renomeado YAML Ain't Markup Language, é um superset estrito do JSON na versão 1.2. Qualquer coisa legal em JSON é YAML legal, mas o YAML adiciona comentários, strings multilinha, âncoras e aliases para reúso, tags de tipo explícitas e, mais importante, uma sintaxe baseada em indentação que retira a maior parte do ruído de pontuação.

Essa legibilidade é o motivo pelo qual o YAML domina configuração. Manifests do Kubernetes, charts do Helm, playbooks do Ansible, GitHub Actions, GitLab CI, Docker Compose, especificações OpenAPI, projetos dbt e a maioria das CLIs modernas leem YAML. Quando um humano vai editar um arquivo em um editor e revisar em um pull request, o YAML vence.

CSV: o aperto de mão universal das planilhas

CSV, comma-separated values, antecede a web e é descrito vagamente pela RFC 4180. É simples ao extremo: a primeira linha geralmente é um cabeçalho, cada linha subsequente é um registro, e os campos são separados por um delimitador (frequentemente uma vírgula, mas tab, ponto e vírgula e pipe são comuns também). Strings que contêm o delimitador, uma quebra de linha ou aspas duplas são envolvidas em aspas duplas, e aspas duplas internas são escapadas duplicando-as.

CSV é o formato que toda planilha da Terra, toda ferramenta de BI, todo carregador em massa de banco de dados e todo analista com um notebook Python entende sem cerimônia. É um formato terrível para dados aninhados e um formato maravilhoso para tabelas planas. Quando o consumidor é um humano com Excel aberto, CSV é quase sempre a resposta certa.

Mesmos dados, três formatos

Vamos cravar as diferenças com um exemplo concreto. Imagine uma lista de três usuários, cada um com um id, um nome, um e-mail, um papel e uma lista de tags. Aqui está a versão JSON.

[
  {
    "id": 1,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "role": "admin",
    "tags": ["founder", "math"]
  },
  {
    "id": 2,
    "name": "Linus Torvalds",
    "email": "linus@example.com",
    "role": "maintainer",
    "tags": ["kernel", "git"]
  },
  {
    "id": 3,
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "role": "admin",
    "tags": ["compiler", "navy"]
  }
]

O mesmo payload em YAML

Note como a pontuação cai. A estrutura é transmitida inteiramente pela indentação, e a lista de tags pode ser escrita inline (estilo flow, idêntico ao JSON) ou como um bloco. Comentários são legais e frequentemente úteis.

# Usuários seed para o ambiente de staging
- id: 1
  name: Ada Lovelace
  email: ada@example.com
  role: admin
  tags:
    - founder
    - math
- id: 2
  name: Linus Torvalds
  email: linus@example.com
  role: maintainer
  tags: [kernel, git]   # estilo flow é bom para listas curtas
- id: 3
  name: Grace Hopper
  email: grace@example.com
  role: admin
  tags:
    - compiler
    - navy

E como CSV

O CSV não consegue expressar nativamente a array aninhada de tags, então temos que achatar. Uma convenção comum é juntar a lista com um delimitador secundário como pipe ou ponto e vírgula e documentar essa escolha em algum lugar. A linha de cabeçalho substitui os nomes dos campos, e cada registro fica em sua própria linha.

id,name,email,role,tags
1,Ada Lovelace,ada@example.com,admin,founder|math
2,Linus Torvalds,linus@example.com,maintainer,kernel|git
3,Grace Hopper,grace@example.com,admin,compiler|navy

Três formatos, três tamanhos

Tamanho de arquivo importa mais do que as pessoas admitem. Pipelines de logging, bundles de navegador e contas de armazenamento todos se importam. Para o exemplo acima as contagens aproximadas de bytes são: JSON em torno de 410 bytes formatado e 290 minificado; YAML em torno de 320 bytes; CSV em torno de 200 bytes. CSV vence facilmente em dados planos porque amortiza os nomes dos campos em cada linha em vez de repeti-los.

Assim que você começa a aninhar, o quadro vira. JSON e YAML ficam aproximadamente constantes por registro enquanto o CSV ou tem que achatar com convenções que você inventa, ou explodir em múltiplas planilhas. Para um único usuário profundamente aninhado com vinte campos, JSON e YAML serão menores e mais claros que qualquer CSV que você possa construir.

Onde cada formato vence na prática

Padrão de uso por equipes reais:

• JSON para APIs HTTP, payloads WebSocket, localStorage do navegador, linhas de log (especialmente JSON Lines), bancos de dados de documentos como MongoDB e qualquer contrato entre serviços.
• YAML para Kubernetes, Helm, Argo, workspaces do Terraform Cloud, pipelines de GitHub ou GitLab CI, especificações OpenAPI e AsyncAPI, configuração de aplicação que humanos editam e infraestrutura como código onde legibilidade vence velocidade de parsing.
• CSV para exportações analíticas, importações de CRM, tabelas de staging de ETL, datasets de machine learning, relatórios financeiros e qualquer coisa destinada ao Excel ou Google Sheets.
• Não recorra a nenhum dos três se seus dados são binários, de muito alto throughput ou fortemente tipados entre serviços. Protobuf, Avro ou Parquet geralmente são a resposta certa lá.

Pegadinhas do JSON que mordem

O minimalismo do JSON é uma feature, mas cria algumas armadilhas. A spec proíbe comentários, então arquivos de configuração escritos em JSON não podem se explicar. Vírgulas finais após o último elemento de array ou objeto são ilegais, mesmo que toda linguagem moderna as aceite. Números são floats de 64 bits por padrão, então qualquer inteiro maior que 2 elevado a 53 perde precisão silenciosamente, razão pela qual muitas APIs serializam IDs grandes como strings.

JSON também não tem tipo nativo de data. Strings ISO 8601 são a convenção de facto, mas você e seu consumidor precisam concordar. E chaves duplicadas no mesmo objeto são tecnicamente permitidas pela gramática, mas produzem comportamento indefinido entre parsers, então não confie nelas.

Pegadinhas do YAML que mordem mais forte

A flexibilidade do YAML é sua fraqueza. A indentação é significativa, então misturar tabs e espaços ou perder dois caracteres de espaço inicial muda silenciosamente o significado do seu arquivo. O famoso problema da Noruega ainda aparece em parsers YAML 1.1: o token NO sem aspas é parseado como o booleano false, o que já estragou listas de códigos de país mais de uma vez. O YAML 1.2 corrige isso, mas muito ferramental ainda distribui semântica 1.1.

Strings que parecem números, datas ou booleanos são coagidas a menos que você as coloque entre aspas. Âncoras e aliases (a sintaxe &foo e *foo) são poderosas mas convidam ataques de negação de serviço estilo billion laughs se você aceitar YAML não confiável. Sempre parseie YAML fornecido pelo usuário com um loader seguro.

Pegadinhas do CSV que mordem em silêncio

O CSV é o formato com maior probabilidade de parecer correto enquanto está sutilmente quebrado. Não há padrão para o delimitador; locales europeus exportam com ponto e vírgula porque a vírgula é separador decimal, e seu importador precisa detectar isso. Quebras de linha dentro de campos com aspas são legais, mas tropeçam em divisores de linha ingênuos. O Excel reformatará felizmente números de telefone e IDs longos como notação científica quando abre um CSV, mutilando seus dados antes que um humano os veja.

Codificação é a outra mina terrestre. CSV não tem declaração de codificação, então um arquivo que abre limpo no macOS pode mostrar mojibake no Windows por causa de UTF-8 versus Windows-1252. Em caso de dúvida, escreva um BOM UTF-8, documente o delimitador e coloque toda string entre aspas.

Convertendo com segurança entre eles

A maioria dos sistemas reais vive em mais de um desses formatos. Você ingere um CSV de um fornecedor, transforma em JSON para uma API e emite YAML para configurar o worker que processa o resultado. Fazer essas conversões à mão é de onde vêm os bugs, razão pela qual o Multilities oferece conversores dedicados.

Se você está alternando entre JSON e YAML, o conversor /tools/yaml-json lida com ambas as direções e preserva comentários quando pode. Para dados tabulares, /tools/csv-json transforma exportações CSV em arrays JSON que você pode colar direto em um arquivo de fixture ou request do Postman, e de volta quando você precisa entregar uma planilha para o financeiro. E quando você só quer um blob JSON que se leia como se um humano tivesse escrito, /tools/json-formatter ordena chaves, corrige indentação e valida a estrutura em uma única passada.

Um checklist de decisão

Quando estiver em dúvida, percorra esta lista de cima para baixo e pare no primeiro sim.

• O consumidor é uma planilha ou um carregador SQL em massa e os dados são planos? Use CSV.
• Um humano vai editar este arquivo em um editor de código e revisá-lo em um pull request? Use YAML.
• O consumidor é um programa, especialmente através da rede, e você quer cerimônia mínima e ferramental máximo? Use JSON.
• Você está serializando milhões de registros em alto throughput com schema fixo? Pule os três e recorra a Protobuf, Avro ou Parquet.

Para fechar

Os três formatos não são tanto concorrentes quanto especialistas. JSON é o formato universal de intercâmbio, YAML é a linguagem amigável a humanos para configuração, e CSV é o aperto de mão de planilhas que se recusa a morrer porque nada mais é tão universalmente entendido por não desenvolvedores. Saber para qual trabalho cada um foi projetado, e saber as pegadinhas, é o que separa equipes que entregam pipelines de dados limpos das equipes que brigam com bugs de escape toda sexta à tarde.

Mantenha as ferramentas de conversão nos favoritos, anote qual delimitador e codificação seus CSVs usam, coloque suas strings YAML entre aspas em caso de dúvida e nunca confie que um ID de 64 bits sem sinal sobreviva a uma viagem de ida e volta pelo JavaScript. Faça isso e o formato que você escolher vai majoritariamente desaparecer no fundo, que é exatamente o que um bom formato de dados deve fazer.