YAML vs JSON em 2026: 7 diferenças essenciais e quando usar cada um

YAML vs JSON — a resposta curta

Se você só precisa de uma linha: use JSON para APIs e troca de dados entre máquinas, e use YAML para arquivos de configuração que você edita à mão. Ambos descrevem o mesmo modelo de dados — objetos, arrays, strings, números e booleanos — mas o JSON é rígido e verboso, enquanto o YAML é baseado em indentação e oferece suporte a comentários.

Pontos principais

• O JSON é rígido, rápido e voltado para máquinas; o YAML é baseado em indentação, voltado para humanos e oferece suporte a comentários
• O JSON vence em APIs, fluxos de logs e parsing de alto desempenho; o YAML vence em configuração editada à mão (Kubernetes, GitHub Actions, Ansible)
• O YAML oferece suporte a comentários, âncoras, strings multilinha e datas como tipos de primeira classe — o JSON não
• Prompts em YAML costumam ser de 10 a 25% mais baratos em contagem de tokens de LLM, mas o JSON faz parsing mais rápido e é mais seguro com entradas não confiáveis

O restante deste artigo percorre as diferenças concretas, mostra os mesmos dados nos dois formatos, compara casos de uso reais e explica as armadilhas a observar quando você converte de um para o outro. Também abordamos uma questão que se tornou comum em 2026: qual formato é mais barato para alimentar um prompt de LLM.

Exemplos do mundo real: onde cada formato é usado

Antes de mergulhar na sintaxe, aqui está o atalho que a maioria das pessoas que programam usa para decidir entre os dois:

• Manifestos do Kubernetes, charts do Helm — YAML
• Arquivos do Docker Compose — YAML
• Pipelines do GitHub Actions, GitLab CI, CircleCI — YAML
• Playbooks do Ansible — YAML
• Corpos de requisição e resposta de APIs REST — JSON
• package.json, composer.json, mensagens do navegador para o servidor — JSON
• Registros de log e fluxos de eventos — JSON Lines
• Especificações OpenAPI / Swagger — YAML ou JSON (autores costumam escolher YAML, geradores frequentemente emitem JSON)

Repare no padrão. O YAML vence quando uma pessoa vai ler ou editar o arquivo. O JSON vence quando um programa vai produzi-lo ou consumi-lo. Essa é a razão de fundo pela qual os formatos evoluíram do jeito que evoluíram, e é a melhor regra prática para escolher um deles.

Lado a lado: os mesmos dados em YAML e JSON

Aqui está uma pequena configuração de servidor web expressa nos dois formatos.

YAML:

# Web server configuration
server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - https://example.com
    - https://staging.example.com
  headers:
    X-Frame-Options: DENY
    Strict-Transport-Security: "max-age=31536000"

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": [
      "https://example.com",
      "https://staging.example.com"
    ],
    "headers": {
      "X-Frame-Options": "DENY",
      "Strict-Transport-Security": "max-age=31536000"
    }
  }
}

Duas coisas se destacam. Primeiro, a versão em YAML é cerca de 30% mais curta porque dispensa a maioria das chaves, colchetes e aspas. Segundo, apenas a versão em YAML consegue carregar o comentário # Web server configuration — a versão em JSON o perde por completo.

Tipos de dados: o que o YAML suporta e o JSON não

Ambos os formatos cobrem strings, números, booleanos, null, objetos e arrays. O YAML acrescenta alguns extras que tornam os arquivos de configuração mais fáceis de escrever.

Datas e timestamps

Os parsers de YAML aceitam datas ISO 8601 como valores de primeira classe:

release_date: 2026-04-01
created_at: 2026-04-01T09:30:00Z

O JSON não tem um tipo de data. As datas precisam ser armazenadas como strings e interpretadas pela aplicação que as recebe:

{
  "release_date": "2026-04-01",
  "created_at": "2026-04-01T09:30:00Z"
}

Strings multilinha

O YAML tem dois operadores para blocos de texto longos. O bloco literal (|) preserva as quebras de linha, enquanto o escalar dobrado (>) as substitui por espaços.

description: |
  This service accepts webhooks from GitHub
  and forwards them to an internal queue.

summary: >
  All traffic is served through Cloudflare,
  and the origin is rate-limited to 100 rps.

O JSON precisa escapar as quebras de linha dentro de uma única linha:

{
  "description": "This service accepts webhooks from GitHub\nand forwards them to an internal queue.\n",
  "summary": "All traffic is served through Cloudflare, and the origin is rate-limited to 100 rps."
}

Inferência de tipos frouxa

O YAML tenta inferir os tipos a partir de valores sem aspas. Dependendo da versão da especificação, yes, no, on e off podem virar booleanos. Valores que parecem números viram números. Isso é conveniente quando humanos escrevem os arquivos, mas também é a fonte do infame "problema da Noruega" — country: NO sendo silenciosamente interpretado como false. O JSON não tem nenhuma dessas ambiguidades: strings sempre ficam entre aspas e números sempre são números.

Comentários: a vantagem do YAML na documentação

Os comentários em YAML começam com # e vão até o fim da linha. Eles são valiosíssimos para explicar por que um ajuste existe.

retries: 3  # Any higher and we exceed the upstream timeout

O JSON não tem sintaxe de comentários. As soluções de contorno comuns — campos "_comment": "..." ou as variantes não padronizadas JSONC e JSON5 — existem justamente porque a falta de comentários torna o JSON penoso para configuração. Para a história completa, veja Como adicionar comentários ao JSON.

Âncoras e aliases: o recurso de reúso do YAML

O YAML permite definir um valor uma única vez com &anchor e referenciá-lo em outro lugar com *alias. A chave de merge <<: então puxa um bloco compartilhado para dentro de um mapeamento.

defaults: &defaults
  adapter: postgres
  host: db.internal
  pool: 5

development:
  <<: *defaults
  database: myapp_dev

production:
  <<: *defaults
  database: myapp_prod
  pool: 20

Quando o arquivo é convertido para JSON, a âncora é expandida inline — tanto development quanto production acabam com uma cópia completa de cada valor padrão. Os dados resultantes estão corretos, mas a intenção original de "estes compartilham os mesmos defaults" deixa de ser visível.

Desempenho, tamanho e velocidade de parsing

Para comunicação entre máquinas, o JSON é a escolha mais rápida. Os parsers de JSON acompanham o runtime de toda linguagem mainstream (JSON.parse, json.loads, encoding/json) e são altamente otimizados. O parsing de YAML é mais lento porque a gramática é mais rica, e a maioria das bibliotecas de YAML acaba construindo internamente uma árvore equivalente à de JSON de qualquer forma.

Os arquivos YAML costumam ser de 20 a 30% menores em disco, mas, uma vez que qualquer um dos formatos é compactado com gzip para transporte, a diferença de tamanho quase desaparece. O custo real do YAML não está nos bytes — está no tempo de CPU do parser e nas surpresas causadas pela inferência implícita de tipos.

Quando escolher YAML

• Uma pessoa vai ler ou editar o arquivo à mão
• O arquivo é configuração, não um payload de dados
• Você precisa de comentários para explicar os ajustes
• A toolchain já espera YAML (Kubernetes, Docker Compose, Ansible, CI)
• Você quer usar âncoras e aliases para reduzir duplicação

Se você tem JSON em mãos e quer uma forma mais legível para humanos, cole-o no JSON para YAML — o conversor preserva o aninhamento e permite conferir a indentação no navegador antes de salvar.

Quando NÃO usar YAML

Mesmo quando o YAML parece a escolha óbvia, há situações em que ele causa mais problemas do que resolve.

• Configuração gerada por máquina — a inferência de tipos transforma version: 2.0 no número 2, corrompendo os dados silenciosamente
• Fluxos de dados em tempo real — a sobrecarga de parsing é significativa em alta vazão
• Entradas sensíveis à segurança — tags YAML como !!python/object podem executar código arbitrário em loaders inseguros; use sempre yaml.safe_load ou equivalente
• Payloads curtos e planos — a economia de indentação desaparece e o JSON é mais simples

Quando escolher JSON

• Um programa vai produzir ou consumir os dados
• Você precisa de interoperabilidade entre linguagens sem surpresas
• Os dados são transmitidos pela rede em uma API
• Você quer parsing rígido e sem ambiguidades, sem coerção de tipos oculta
• O desempenho importa — o parsing precisa ser rápido e previsível

Quando você precisa alimentar YAML escrito à mão em um programa que só fala JSON, o YAML para JSON faz a conversão no navegador com erros numerados por linha — útil para pegar surpresas de inferência de tipos antes que cheguem à produção.

Armadilhas comuns ao converter YAML para JSON

A conversão é, em sua maioria, sem perdas, mas um punhado de casos extremos costuma derrubar as pessoas.

• Os comentários desaparecem — o JSON não tem sintaxe de comentários, então cada linha # é descartada
• As âncoras são expandidas — blocos compartilhados viram dados duplicados
• As datas viram strings — datas ISO perdem a informação de tipo
• Surpresas de inferência de tipos — um valor YAML como version: 2.0 vira o número 2 em JSON
• Arquivos com múltiplos documentos — o YAML pode conter vários documentos separados por ---; o JSON precisa escolher um ou envolvê-los em um array externo
• Chaves duplicadas — o comportamento do YAML depende da implementação; em JSON só o último valor prevalece
• Tags e tipos personalizados — o !!timestamp do YAML ou tags personalizadas não têm representação direta em JSON

Para o passo a passo, veja Como converter YAML para JSON. Depois de ter o JSON, Dicas de formatação de JSON cobre indentação, ordenação de chaves e outras escolhas que mantêm a saída revisável.

Converta YAML ⇄ JSON com o FormatArc

O FormatArc executa a conversão inteiramente no navegador — sem upload, sem cadastro, nada sai da sua máquina.

• YAML para JSON — cole o YAML e obtenha JSON, com mensagens de erro numeradas por linha quando a sintaxe estiver incorreta
• JSON para YAML — direção inversa, produz YAML limpo com o aninhamento preservado
• Formatador de JSON — formate o JSON resultante com relatório de erros legível

Se você prefere um fluxo via script, o yq e o yaml.safe_load do Python funcionam bem. Um one-liner rápido em Python:

python3 -c "import yaml,json,sys; print(json.dumps(yaml.safe_load(sys.stdin),indent=2))" < config.yaml

Perguntas frequentes

O YAML é um superconjunto do JSON?

Desde o YAML 1.2, todo JSON válido também é YAML válido. Um parser de YAML consegue ler um arquivo JSON diretamente. O contrário não é verdade — um parser de JSON não consegue ler YAML. Na prática, muitas bibliotecas de YAML ainda usam por padrão a especificação mais antiga, YAML 1.1, em que essa compatibilidade é menos confiável.

Por que o Kubernetes e o Docker Compose usam YAML em vez de JSON?

Porque seus arquivos de configuração são editados por humanos, e a sintaxe baseada em indentação do YAML, com comentários, é mais fácil de manter para configuração extensa. Quando essas ferramentas emitem estado (por exemplo, kubectl get ... -o json), elas normalmente oferecem um modo JSON para consumo por máquinas.

O YAML faz parsing mais rápido que o JSON?

Não. O JSON faz parsing significativamente mais rápido em toda linguagem mainstream. O YAML é mais lento porque sua gramática é mais rica e ambígua. Para transporte de dados sensível ao desempenho, o JSON é a escolha certa.

Posso converter JSON para YAML sem perder dados?

Sim. A conversão de JSON para YAML é quase sempre sem perdas porque o JSON é o formato mais simples. Você não consegue adicionar comentários que o JSON nunca teve, mas os dados em si fazem o round-trip de forma limpa. Cole sua entrada no conversor de JSON para YAML para ver o resultado.

Por que meu valor YAML country: NO vira false?

Esse é o famoso "problema da Noruega". Parsers de YAML mais antigos interpretam NO sem aspas como o booleano false. Corrija colocando o valor entre aspas: country: "NO". A especificação YAML 1.2 removeu esse comportamento, mas muitas ferramentas ainda usam a 1.1 por padrão.

YAML vs JSON para prompts de LLM — qual usa menos tokens?

O YAML costuma ser mais barato. Tokenizadores como o cl100k_base da OpenAI e o tokenizador da Anthropic tratam chaves, colchetes e aspas repetidas como tokens separados, então JSON profundamente aninhado paga uma taxa estrutural que o YAML evita com indentação. Para os mesmos dados, prompts em YAML costumam ser de 10 a 25% mais curtos em contagem de tokens. O trade-off é que alguns modelos seguem a saída em JSON estrito de forma mais confiável do que em YAML. Um padrão comum em 2026 é: alimente com YAML na entrada e peça JSON na saída.

Os comentários em YAML sobrevivem a um round-trip por JSON?

Não. Os comentários estão atrelados a posições de linha no arquivo de origem, não a campos na estrutura de dados. Depois que o YAML é interpretado, os comentários são descartados. Converter YAML para JSON e de volta sempre vai perdê-los — mantenha o YAML original se você precisar dos comentários preservados.

Leitura relacionada

• Como converter YAML para JSON — guia de conversão passo a passo com exemplos
• Guia de conversão de JSON para YAML — a direção inversa
• O que é YAML? — fundamentos de YAML para iniciantes
• Guia de sintaxe do YAML — escreva YAML válido do zero
• Dicas de formatação de JSON — produza JSON revisável após a conversão
• Como adicionar comentários ao JSON — JSONC, JSON5 e soluções de contorno
• O que é JSON? — fundamentos de JSON para iniciantes

Resumo

• YAML e JSON descrevem o mesmo modelo de dados; a diferença está em quem vai ler o arquivo
• Escolha YAML para configuração editada à mão com comentários, escolha JSON para troca de dados entre máquinas
• Fique atento à inferência de tipos, à expansão de âncoras e à perda de comentários ao converter YAML para JSON
• O FormatArc converte nas duas direções no navegador, com relatório de erros numerado por linha