JSON vs YAML vs CSV - qual formato de dados usar e quando

JSON, YAML e CSV guardam dados estruturados, mas nao sao intercambiaveis. O mesmo registro de pessoa fica limpo nos tres - ate voce precisar de enderecos aninhados, booleanos tipados, comentarios em config ou uma planilha que o colega abre no Excel. Escolha o formato errado e voce perde tipos, achata arvores em colunas estranhas ou leva uma surpresa do parser, como YAML transformar o codigo de pais NO em false. Este guia coloca JSON vs YAML vs CSV lado a lado, mostra quando cada um ganha e aponta os conversores gratis no ToolsMinify.

O mesmo registro nos tres formatos

Comece com um objeto: um id, um nome, uma flag active e tags. Veja como esse registro aparece em cada formato para comparar a sintaxe de relance.

JSON

• {"id": 42, "name": "Ada", "active": true, "tags": ["admin", "beta"]}
• Chaves entre aspas, virgulas entre campos, colchetes para arrays, true/false/null como literais.
• Sem comentarios. Virgulas finais sao invalidas em JSON padrao.

YAML

• id: 42
• name: Ada
• active: true
• tags:
• - admin
• - beta
• Indentacao define a estrutura. Aspas costumam ser opcionais. Comentarios comecam com #.

CSV

• id,name,active,tags
• 42,Ada,true,"admin;beta"
• Uma linha de cabecalho, depois uma linha por registro. Arrays aninhados viram string achatada ou colunas extras. Sem tipos nativos alem de texto.

Ja esta olhando um array JSON de objetos? Cole no Conversor JSON para CSV para gerar uma tabela amigavel para planilha. Indo config na outra direcao? Use o Conversor YAML para JSON antes de um cliente de API que so fala JSON.

JSON: o padrao de API e interchange

JSON (JavaScript Object Notation) e um subconjunto da sintaxe de objeto JavaScript que toda linguagem importante consegue fazer parse. Objetos, arrays, strings, numeros, booleanos e null sao de primeira classe. Aninhamento e ilimitado, entao um objeto de endereco dentro de um usuario e natural. Por isso respostas REST e GraphQL, bodies de webhook e muitos stores de config usam JSON.

• Melhor para: corpos de request e response de API, clientes web e mobile, filas de mensagens, qualquer coisa que precise round-trip por varias linguagens.
• Pontos fortes: gramatica estrita, tipos previsiveis, tooling excelente, facil de minificar e embelezar.
• Limites: sem comentarios, sem strings multilinha sem escape, sem ancoras ou merges. Humanos editando JSON grande na mao geram diffs ruidosos.

Quando um payload chega em uma linha comprimida, abra o Minificador e formatador JSON para embelezar, validar chaves e minificar de novo antes de publicar.

YAML: config que as pessoas realmente editam

YAML (YAML Ain't Markup Language) e pensado para humanos primeiro. Indentacao substitui a maior parte das chaves. Voce pode deixar comentarios com #, escrever blocos multilinha com | ou >, e reutilizar blocos com ancoras (&name) e aliases (*name). Essa combinacao fez YAML virar padrao em manifests Kubernetes, Docker Compose, GitHub Actions e muitos arquivos de config de app.

Comentarios e ancoras

Comentarios sao o recurso que JSON nao tem. Uma linha comecando com # documenta por que um timeout e 30 segundos sem mudar dados de runtime. Ancoras vao alem: defina um bloco de logging compartilhado uma vez com &logging, depois puxe em varios servicos com *logging, opcionalmente sobrepondo chaves com <<:. Usadas com cuidado, ancoras cortam duplicacao. Usadas de forma descuidada, deixam arquivos dificeis de ler e surpreendentes de mergear no Git.

• Melhor para: config de deploy e CI, feature flags que humanos editam, documentos pequenos onde legibilidade vence tamanho no wire.
• Pontos fortes: comentarios, ancoras/aliases, strings multilinha, menos ruido de pontuacao.
• Limites: bugs de indentacao, surpresas de tipagem implicita e superficie de ataque maior se voce faz parse de YAML nao confiavel com loaders inseguros.

CSV: tabelas planas para planilhas

CSV (Comma-Separated Values) e uma grade: colunas e linhas. Planilhas, ferramentas de BI e pipelines de dados entendem. Nao ha objeto aninhado, nem tipo array, e em geral nem tipo booleano - tudo e texto ate seu importador fazer cast. Isso e ok quando seus dados ja sao uma tabela de usuarios ou pedidos. Quebra quando a fonte e uma arvore.

Por que CSV perde tipos e aninhamento

• Tipos: "42", 42 e true chegam como strings a menos que voce defina um schema. Zeros a esquerda em ids e telefones somem no Excel.
• Aninhamento: um endereco com rua e cidade vira colunas address.street, um blob JSON numa celula ou linhas pai duplicadas.
• Arrays: tags viram uma celula com delimitador (admin;beta), que voce precisa separar depois.
• Null vs vazio: celula vazia pode significar null, string vazia ou coluna ausente - convencoes variam.

Se a fonte e JSON aninhado, converta de proposito com o Conversor JSON para CSV e decida como arrays e chaves aninhadas devem achatar antes de entregar o arquivo a uma planilha.

Quando cada formato e a escolha certa

APIs e maquina para maquina

Prefira JSON. Clientes esperam application/json, tooling esta em todo lugar e o sistema de tipos e bom o bastante para a maioria dos contratos. YAML como body HTTP e raro e em geral um erro. CSV como resposta de API so faz sentido em endpoints de export em massa que alimentam Excel ou data warehouses.

Arquivos de config

Prefira YAML (ou um formato tipado como TOML) quando humanos editam o arquivo e precisam de comentarios. Prefira JSON quando a config e gerada, validada por schema ou editada sobretudo por ferramentas. Mantenha documentos YAML pequenos e revisados - ancoras profundas e tags custom envelhecem mal.

Planilhas e analytics

Prefira CSV (ou um formato de planilha de verdade) quando o consumidor e Excel, Google Sheets ou um SQL COPY. Achate o modelo primeiro. Guarde JSON como system of record e exporte CSV como visao.

Armadilhas classicas

O problema da Noruega no YAML

No YAML 1.1, varias strings sem aspas viram booleanos no parse: yes, no, on, off, true, false (e algumas variantes de locale). O codigo de pais NO da Noruega vira boolean false. Strings de versao como 1.10 podem virar float. Coloque aspas em valores que parecem booleanos, numeros ou datas quando sao strings de verdade: country: "NO". Prefira parsers YAML 1.2 quando puder, e ainda assim coloque aspas em escalares suspeitos.

Virgulas no CSV dentro de campos entre aspas

Campos com virgulas, aspas ou quebras de linha precisam ficar entre aspas duplas. Aspas dentro do campo escapam duplicando: "Ada ""Lovelace""". Um split ingenuo por virgulas quebra essas linhas. Sempre use um parser ou exportador CSV de verdade - inclusive ao fazer round-trip pelo Conversor JSON para CSV. Configuracao de locale tambem importa: algumas regioes usam ponto e virgula como separador enquanto o Excel ainda espera virgulas ou vice-versa.

Outras pegadinhas

• JSON: virgulas finais e comentarios de literais de objeto JavaScript falham em parsers estritos.
• YAML: tabs vs espacos, loaders inseguros que executam tags e documentos enormes que escondem erros de merge.
• CSV: nenhum padrao unico para encoding, delimitador ou fim de linha; documente sempre UTF-8 e seu separador.

Comparacao lado a lado

• Aninhamento - JSON e YAML: arvores naturais. CSV: achata ou perde estrutura.
• Tipos - JSON: string, number, bool, null, array, object. YAML: escalares mais ricos (mais surpresas). CSV: texto ate cast.
• Comentarios - JSON: nenhum. YAML: comentarios #. CSV: sem comentarios padrao.
• Edicao humana - YAML costuma ganhar; JSON ok para arquivos pequenos; CSV ganha dentro de planilhas.
• Wire / API - JSON e o padrao. YAML e CSV sao casos de borda.
• Tooling - converta com JSON para CSV e YAML para JSON; formate JSON com o Minificador e formatador JSON.

Perguntas frequentes

YAML e melhor que JSON?

Para config editada por humanos com comentarios, muitas vezes sim. Para APIs e interchange, JSON e melhor: mais estrito, mais previsivel e universalmente suportado. Muitos times escrevem YAML e compilam ou convertem para JSON em runtime.

CSV representa JSON aninhado?

So achatando. Objetos aninhados viram colunas com ponto ou strings JSON-numa-celula; arrays viram listas com delimitador ou linhas repetidas. Use CSV quando o consumidor precisa de tabela, nao quando precisa preservar a arvore inteira.

Devo guardar config em JSON ou YAML?

Se pessoas editam toda semana e deixam comentarios, YAML (ou TOML). Se um validador de schema ou codegen manda no arquivo, JSON. Evite misturar os dois para a mesma fonte da verdade.

O que e o problema da Noruega no YAML?

NO sem aspas (e tokens parecidos) pode virar boolean false no parse do YAML 1.1. Coloque aspas em codigos de pais e outros escalares stringy, ou use parser YAML 1.2 que os trata como strings.

Como converto entre esses formatos?

Use o Conversor YAML para JSON para levar config ao formato de API, e o Conversor JSON para CSV para export tabular. Embeleze ou minifique JSON com o Minificador e formatador JSON. Os tres rodam no navegador.

Converta JSON, YAML e CSV no ToolsMinify

Cada ferramenta abaixo roda inteira no navegador - gratis, sem cadastro, nada enviado:

• Conversor JSON para CSV - transforme um array JSON de objetos em tabela CSV para download.
• Conversor YAML para JSON - faca parse de config YAML em JSON para APIs e validadores.
• Minificador e formatador JSON - embeleze ou minifique JSON e pegue erros de sintaxe cedo.
• Todas as ferramentas de conversao - o indice completo da categoria.