JSON vs YAML vs CSV vs Markdown: Cheatsheet de Comparação de Formatos de Dados

JSON, YAML, CSV e Markdown são quatro formatos de texto com estrutura, mas cada um foi projetado para um trabalho diferente. Use CSV em um arquivo de configuração e a estrutura fica plana. Escolha YAML para uma resposta de API e você perde o rigor que queria. Guarde dados tabulares em JSON e cada linha repete as chaves. Trate Markdown como armazenamento primário e você terá que reconstruir a estrutura depois. Escolher o formato errado custa caro em ferramentas, validação e horas de desenvolvimento.

Este artigo é um cheatsheet de uma página para responder "qual formato eu uso?". Começa com uma matriz de decisão rápida e segue com tabela de recursos, suporte a comentários, ecossistema de parsers, matriz de decisão por caso de uso, erros comuns, escolha para contexto de LLM e referências de specs — tudo em uma única aba.

Matriz de decisão rápida — escolha um formato

Se você ler só uma tabela, leia esta.

Versão curta: JSON para troca entre máquinas, YAML para configuração editada à mão, CSV para dados tabulares, Markdown para prosa. Depois você ajusta nos extremos pelas exceções abaixo.

Teste primeiro — converta entre os quatro formatos no navegador

As diferenças ficam mais claras quando você coloca o mesmo dado nos quatro formatos. O FormatArc tem sete ferramentas browser-side para converter entre os quatro formatos cobertos aqui. Sem upload, sem ida ao servidor — o que você cola fica na sua aba.

• JSON Formatter — validar e formatar JSON
• YAML to JSON / JSON to YAML — ida e volta entre YAML e JSON
• CSV to JSON — transformar dados tabulares em um array estruturado
• CSV to Markdown — converter uma coluna de planilha em tabela Markdown
• Markdown to HTML / HTML to Markdown — converter entre formatos de documento

Se você já hesitou em colar dados de produção em uma ferramenta online que envia ao servidor dela, veja Conversores online são seguros? para um modelo de avaliação desse risco.

O que este artigo cobre — e o que não cobre

Comparamos quatro formatos: JSON, YAML, CSV e Markdown. É a combinação mais frequente no desenvolvimento web moderno, em configuração, em troca de dados e em documentação, e bate exatamente com as sete ferramentas do FormatArc.

Fora de escopo, por escolha:

• XML — ainda importante para SOAP, RSS, SVG e Office Open XML, mas raramente escolhido para projetos novos.
• TOML — usado pelo Cargo e pyproject.toml. Sobrepõe-se a YAML e JSON5 no espaço de configuração e é incomum em trabalho para navegador.
• Parquet — formato binário colunar para big data. Fora do escopo de uma comparação entre formatos de texto.
• XLSX / ODS — formatos binários de planilha. Aparecem só pelo caminho de exportação em CSV.

Se você quer uma comparação de cinco formatos com XML ou TOML, existem vários concorrentes. O ângulo aqui é outro: Markdown recebe tratamento de primeira, porque em 2026 ele está ao lado de JSON e YAML no fluxo diário de quem escreve APIs, configurações, READMEs e prompts para LLM.

O mesmo dado nos quatro formatos

Lado a lado, com dois usuários, idades e uma lista de habilidades, os formatos mostram a personalidade de cada um.

JSON

{
  "users": [
    { "name": "Alice", "age": 30, "skills": ["Python", "Go"] },
    { "name": "Bob",   "age": 25, "skills": ["JavaScript"] }
  ]
}

YAML

users:
  - name: Alice
    age: 30
    skills:
      - Python
      - Go
  - name: Bob
    age: 25
    skills:
      - JavaScript

CSV

CSV não expressa aninhamento de forma nativa, então skills precisa ser achatado. Padrões comuns são juntar por um delimitador, expandir em várias colunas ou separar em outra tabela. A versão mais simples com delimitador:

name,age,skills
Alice,30,Python;Go
Bob,25,JavaScript

Markdown

Markdown é um formato de documento, não de dados. A estrutura acontece via extensão de tabelas do GFM.

| name  | age | skills      |
|-------|-----|-------------|
| Alice | 30  | Python, Go  |
| Bob   | 25  | JavaScript  |

A mesma informação em quatro formas. JSON é estrito e fácil de parsear. YAML lê naturalmente. CSV brilha em tabelas mas não aninha. Markdown fica bem ao renderizar mas perde a estrutura se for tratado como armazenamento de dados.

Matriz de recursos por formato

O que cada formato consegue de fato expressar?

JSON e YAML compartilham o mesmo modelo de dados subjacente (objetos, arrays, primitivos), por isso o round-trip entre eles é direto. O FormatArc oferece YAML to JSON e JSON to YAML nas duas direções. Para um aprofundamento na comparação de só dois formatos, veja YAML vs JSON: 7 diferenças.

Matriz de suporte a comentários

É aqui que a escolha de formato de configuração se decide de verdade. Os padrões e dialetos divergem nesse ponto.

Comentários em JSON surgem com frequência. Não são permitidos no JSON padrão e o JSON.parse lança erro. Veja Dá para escrever comentários em JSON? para as saídas com JSON5 / JSONC / pré-processamento.

Comparação de ecossistema de parsers

Quando você usa a biblioteca padrão de uma linguagem, o que vem incluso?

JSON e CSV vêm na biblioteca padrão em quase todo lugar. YAML e Markdown dependem de bibliotecas externas, embora as escolhas de facto sejam estáveis. O FormatArc traz yaml, papaparse, marked, turndown e remark para o bundle do navegador, e é isso que viabiliza a conversão sem servidor.

Matriz de decisão por caso de uso

Nas decisões reais você não pergunta "qual formato lê melhor?", você combina um caso de uso concreto com um formato. Procure a sua linha.

Escrever tabelas Markdown à mão é chato, então mantenha um CSV ou JSON como fonte e use CSV to Markdown para gerar a tabela. Veja Tabelas em README do GitHub a partir de CSV ou JSON para o fluxo completo.

Escolhas ruins comuns

Padrões que se repetem em times diferentes.

CSV para dados aninhados

Tentar caber { "user": { "address": { "city": "Tokyo" } } } em CSV obriga a inventar uma convenção de achatamento que o consumidor terá que reverter. Se você precisa de aninhamento, use JSON ou YAML, ou divida em um conjunto relacional de CSVs e junte do lado do consumidor.

Cair na tipagem implícita do YAML

O YAML 1.1 convertia no, yes, on, off em booleanos. O famoso "problema da Noruega" é o código de país NO virando silenciosamente false. O YAML 1.2 corrigiu parte disso, mas muitos parsers ainda usam por padrão o modo compatível com 1.1. Coloque entre aspas qualquer string que possa ser confundida com booleano.

country: "NO"   # seguro — string explícita
country:  NO    # pode virar false em um parser compatível com YAML 1.1

Escrever comentários em JSON padrão

O settings.json do VS Code permite comentários, o que leva à suposição de que o JSON padrão também permite. Não permite. O settings.json é JSONC, um dialeto não padrão. O JSON.parse dá erro em qualquer comentário. Se você precisa de comentários, escolha JSON5, JSONC ou YAML, ou remova-os em uma etapa de pré-processamento.

Subestimar a variação de dialetos do CSV

A RFC 4180 é uma referência; o CSV do mundo real é um enxame de dialetos. Delimitadores (, \t ; |), fim de linha (LF vs CRLF), aspas, BOM, encoding de caracteres, presença de cabeçalho e escape de quebras de linha dentro de valores variam de acordo com quem escreveu. "É só CSV" já custou mais horas de debug do que YAML. Verifique os dois lados com uma amostra antes de subir para produção.

Tratar Markdown como formato de dados legível por máquina

Markdown é um formato de documento. As tabelas dele são uma extensão GFM, não fazem parte do CommonMark, e células com pipe ou quebra de linha quebram em renderizadores que não são GFM. Veja Tabela Markdown não renderiza para os modos de falha mais comuns.

Achar que tabelas Markdown são CommonMark

Não são. A sintaxe de tabela é território de GFM, MultiMarkdown ou Pandoc. Um renderizador em modo CommonMark estrito vira sua tabela em um parágrafo feio. GitHub, Dev.to, Zenn e Qiita são amigáveis a GFM; mecanismos de blog antigos e wikis podem não ser. Veja CommonMark vs GFM para o limite.

Escolha para contexto de LLM

Para entrada de ChatGPT, Claude ou Gemini, Markdown é o padrão. Usa aproximadamente de um terço a um décimo dos tokens do HTML equivalente, e benchmarks externos mostram consistentemente maior precisão de extração em tabelas, listas e blocos de código. Para saída estruturada de LLM (function calling, modo JSON), JSON é obrigatório. O padrão assimétrico — Markdown na entrada, JSON na saída — é o que a maioria dos prompts em produção acaba adotando.

YAML é arriscado como entrada de LLM porque a indentação é frágil sob tokenização e a tipagem implícita pode transformar strings em booleanos. Os números em nível de token e o caminho de conversão sem upload estão detalhados em Markdown vs HTML para LLMs.

Specs e história

Tabela de referência para quem decide.

JSON e CSV têm RFCs estáveis. YAML e Markdown têm famílias de dialetos vivos (YAML 1.1 vs 1.2; CommonMark vs GFM vs MultiMarkdown vs Pandoc). Sempre verifique o dialeto do consumidor quando interoperabilidade importa.

Para os fundamentos de cada formato:

• O que é JSON? — sintaxe e casos de uso
• O que é YAML? — sintaxe e casos de uso
• O que é CSV? — sintaxe e casos de uso

Converta entre formatos com as sete ferramentas do FormatArc

As sete rotas canônicas de conversão entre os quatro formatos vivem no navegador no FormatArc. Nada do que você cola sai da sua aba.

Encadeadas, você consegue fluxos como "JSON de API para YAML de configuração", "Excel para CSV para tabela Markdown no README", ou "HTML de página web para Markdown para um prompt do ChatGPT" — tudo no navegador.

Resumo

A lista final para quando você precisa escolher rápido.

• Troca de dados entre máquinas: JSON
• Configuração editada à mão: YAML
• Dados tabulares: CSV
• Prosa legível por humanos: Markdown
• Entrada LLM: Markdown; saída LLM: JSON

Não existe formato "certo". Existe o formato que otimiza o que importa pra você — legibilidade, rigor, amplitude de parsers, suporte a comentários, eficiência de tokens em LLM. Use as matrizes acima como tabela de consulta única na próxima vez que iniciar um projeto.

Referências de specs:

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• YAML 1.2.2 Specification
• RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files
• CommonMark Specification
• GitHub Flavored Markdown Spec