TOML vs JSON vs YAML: qual formato de config usar?

Aqui vai a versão curta de TOML vs JSON vs YAML: JSON é o padrão de intercâmbio entre máquinas que toda linguagem consegue interpretar, YAML é o formato amigável para humanos que roda Kubernetes e pipelines de CI, e TOML é o formato explícito e tipado feito para config de ferramentas e aplicações como Cargo.toml e pyproject.toml. Nenhum formato ganha em todos os cenários. O formato de arquivo de configuração certo depende de três coisas: quem edita, se você precisa de comentários e quão rígidos os tipos precisam ser.

Uma regra prática rápida. Se uma máquina escreve e uma máquina lê, use JSON. Se uma pessoa edita à mão, todo dia, uma infraestrutura profundamente aninhada, YAML compensa a complexidade. Se você quer uma configuração óbvia e tipada, difícil de errar, TOML é a escolha mais segura. Esses formatos não são exatamente concorrentes. Eles ocupam faixas diferentes: JSON para máquinas, YAML para DevOps, TOML para config de tooling. O resto deste guia sustenta isso com exemplos lado a lado, as diferenças que de fato causam bugs e uma matriz de decisão que você pode aplicar no seu próximo projeto.

A resposta em 30 segundos

Se você só tem meio minuto, esta tabela é a comparação de formatos de arquivo de configuração que você veio buscar.

	JSON	YAML	TOML
Comentários	Não	Sim (#)	Sim (#)
Tipos de dados	Explícitos, mínimos	Implícitos (inferidos da forma)	Explícitos, ricos
Datas nativas	Não	Depende da versão	Sim (quatro tipos)
Estilo de aninhamento	Chaves {}	Indentação	Cabeçalhos [section]
Sensível à indentação	Não	Sim (tabs proibidos)	Não
Strings multilinha	Não (só \n)	Sim (| e >)	Sim (""")
Vírgulas finais	Proibidas	N/A	Permitidas em arrays
Superconjunto de JSON	—	Sim (1.2)	Não
Melhor para	APIs, troca de dados	K8s, CI, Ansible	Config de tooling Rust/Python

Três vereditos de uma linha decorrem dessa tabela:

• Escolha JSON quando o arquivo é produzido e consumido por programas: payloads de API, package.json, tsconfig.json, qualquer coisa que cruze a fronteira de um sistema.
• Escolha YAML quando humanos editam à mão configuração profunda e aninhada e o ecossistema já espera isso: manifestos Kubernetes, GitHub Actions, Docker Compose, playbooks Ansible.
• Escolha TOML quando você quer uma config clara e tipada para uma ferramenta ou aplicação, majoritariamente plana com algumas seções, editada por colaboradores de nível variado: Cargo.toml, pyproject.toml, Hugo, Netlify.

As razões por trás desses vereditos importam, porque é nelas que os bugs de verdade se escondem.

A mesma config, de três jeitos

A forma mais rápida de ver a diferença é escrever a mesma configuração três vezes. Aqui vai uma pequena config de serviço: um nome e uma versão, algumas flags de nível superior, uma lista de recursos e um bloco de banco de dados aninhado.

JSON:

{
  "name": "acme-api",
  "version": "2.4.0",
  "debug": false,
  "released": "2026-07-02",
  "features": ["auth", "metrics", "tracing"],
  "database": {
    "host": "db.internal",
    "port": 5432,
    "max_connections": 100
  }
}

YAML:

name: acme-api
version: "2.4.0"
debug: false
released: "2026-07-02"
features:
  - auth
  - metrics
  - tracing
database:
  host: db.internal
  port: 5432
  max_connections: 100

TOML:

name = "acme-api"
version = "2.4.0"
debug = false
released = "2026-07-02"
features = ["auth", "metrics", "tracing"]

[database]
host = "db.internal"
port = 5432
max_connections = 100

Os três descrevem exatamente os mesmos dados. Repare no que seu olho tropeça. JSON carrega a maior quantidade de pontuação: toda chave vem entre aspas duplas, cada nível adiciona chaves, e uma única vírgula final perdida é um erro de sintaxe. YAML tira quase tudo isso, então a estrutura vem só da indentação, o que se lê lindamente até que um tab entre sorrateiramente. TOML fica no meio: aspas só nas strings, pares key = value e um cabeçalho [database] que nomeia o bloco aninhado do jeito que um velho arquivo INI faria. Note que o campo released é uma string entre aspas nos três, para que os dados fiquem idênticos aqui. Isso é proposital, porque datas são justamente onde esses formatos param de concordar.

JSON — o padrão de intercâmbio entre máquinas

JSON é o formato que você usa sem pensar, e normalmente esse instinto está certo. Toda linguagem popular traz um parser, toda API HTTP fala JSON, e sua gramática é pequena o bastante para caber na cabeça. Ele é rígido e sem ambiguidade: uma string é uma string, 5432 é um número, true é um booleano, e há exatamente uma forma de escrever cada um. Essa rigidez é o que torna o JSON seguro para trafegar entre sistemas que nunca se encontraram. Quando um serviço Node envia JSON para um serviço Go, ambos concordam no significado byte a byte.

Essa mesma rigidez é a razão de o JSON dominar seu próprio território. package.json, tsconfig.json e composer.json são JSON porque ferramentas os geram e reescrevem o tempo todo, e config escrita por máquina quer um formato rígido para máquina. Para payloads de API e filas de mensagens, simplesmente não há motivo para escolher outra coisa.

As fraquezas do JSON aparecem todas no momento em que um humano precisa editá-lo à mão. Não há comentários. Não há vírgulas finais, então reordenar uma lista significa consertar vírgulas. Não há strings multilinha, só escapes \n. Toda chave precisa de aspas duplas. E não há tipo de data, então 2026-07-02 tem que viver como uma string entre aspas e ser interpretada por convenção. Para um arquivo de configuração que uma pessoa mantém, essas lacunas somam atrito.

O problema do “JSON não tem comentários”

O recurso mais pedido do JSON é justamente o que Douglas Crockford deixou de fora de propósito: comentários. O raciocínio dele era que comentários convidavam as pessoas a contrabandear diretivas de parsing para dentro de arquivos de config, quebrando a interoperabilidade. Concordando ou não com essa decisão, você não consegue anotar uma config JSON pura, o que dói em qualquer coisa que humanos mantenham. A correção prática é um superconjunto. JSON5 adiciona comentários, vírgulas finais, chaves sem aspas e aspas simples; JSONC (JSON with Comments) é a variante mais leve que o VS Code usa nas suas configurações. Ambos mantêm a forma do JSON, mas o deixam editável. Se você precisa de comentários mas quer permanecer na família JSON, leia nosso guia de formatação JSON5 e JSONC para saber quando usar cada um e como manter o tooling feliz.

YAML — o padrão de DevOps amigável para humanos

YAML otimiza para o humano no teclado. Ele suporta comentários, seu layout baseado em indentação mantém estruturas profundamente aninhadas limpas, e âncoras permitem definir um bloco uma vez e reutilizá-lo com um alias em vez de copiar e colar:

defaults: &defaults
  timeout: 30
  retries: 3

staging:
  <<: *defaults
  host: staging.internal

production:
  <<: *defaults
  host: prod.internal

A âncora &defaults nomeia um bloco, e <<: *defaults o mescla nos dois ambientes, de modo que uma mudança no timeout compartilhado acontece em um só lugar. Nem JSON nem TOML têm algo parecido. Essa legibilidade é a razão de o YAML ter virado a língua franca das operações: manifestos Kubernetes, workflows do GitHub Actions, arquivos Docker Compose e playbooks Ansible são todos YAML. Quando sua config tem cinco níveis de profundidade e um humano a ajusta diariamente, a baixa pontuação do YAML é um alívio genuíno.

O custo é complexidade e surpresa. A especificação do YAML 1.2 é grande, e a conformidade total é rara, então parsers diferentes discordam nas bordas. A indentação é significativa, tabs são terminantemente proibidos, e um espaço desalinhado pode mudar o significado ou falhar no parsing. A borda mais afiada é a tipagem implícita: o YAML adivinha o tipo de um escalar sem aspas a partir de sua forma, e adivinha errado com frequência suficiente para ter ganhado um apelido.

O problema da Noruega em um parágrafo

Escreva country: NO em YAML e muitos parsers te entregam o booleano false, não a string "NO", porque o YAML 1.1, que a maioria do tooling Kubernetes ainda segue, trata NO, YES, ON, OFF, Y e N como booleanos. O código do país da Noruega vira false, silenciosamente, sem erro nenhum. A mesma tipagem implícita transforma 0755 em um número octal e 1.20 em 1.2. A correção é sem graça, mas confiável: coloque entre aspas as strings que poderiam ser confundidas com outra coisa. Essa cilada é famosa o bastante para merecer seu próprio aprofundamento, incluindo panes reais e a história do YAML 1.1 versus 1.2, no nosso guia do problema da Noruega no YAML. Para este artigo, a lição é simples: a conveniência do YAML e o seu perigo vêm do mesmo recurso.

YAML vence quando pessoas editam config profundamente aninhada todo dia e o ecossistema ao redor já a exige. Se você está escrevendo um chart Helm, você está escrevendo YAML, e tudo bem.

TOML — config explícita feita para tooling

TOML (Tom’s Obvious, Minimal Language, criado por Tom Preston-Werner) foi projetado para ser o formato de config que os usuários de YAML gostariam de ter: legível, mas sem a adivinhação. Sua característica definidora é a explicitude. Os tipos são inequívocos, então port = 5432 é sempre um inteiro e name = "acme" é sempre uma string, sem inferência baseada em forma para tropeçar. A sintaxe do TOML pega emprestado o cabeçalho [section] dos arquivos INI, o que torna o nível superior de uma config fácil de varrer com os olhos, e ela não é sensível à indentação, então o espaço em branco nunca muda o significado. A especificação do TOML 1.0.0 é pequena e estável, o que é uma vantagem: há menos coisa para lembrar errado.

O recurso de destaque do TOML são os tipos nativos de data e hora, que nem JSON nem YAML puro tratam de forma limpa. Ele tem quatro deles: date-time com offset e fuso horário (1979-05-27T07:32:00Z), date-time local sem fuso, date local (1979-05-27, apenas um dia do calendário) e time local (07:32:00). Isso significa que uma data de deploy continua uma data de verdade em vez de uma string que você precisa reinterpretar.

Três pedaços da sintaxe TOML fazem a maior parte do trabalho. Um cabeçalho [section] abre uma tabela; um cabeçalho com pontos como [tool.ruff] aninha uma tabela dentro de outra sem indentação extra; e uma tabela inline { version = "1.0", features = ["derive"] } empacota um pequeno objeto em uma única linha. Seções repetidas usam um cabeçalho duplicado, o array de tabelas:

[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"

Esse bloco vira um array JSON de dois objetos sob a chave servers. Ele se lê bem para uma lista plana, que é exatamente o que a maioria das configs de ferramenta precisa.

As fraquezas são reais, mas restritas. TOML não tem tipo null, então um valor ausente é simplesmente uma chave omitida. Aninhamento profundo fica verboso, porque cada nível de uma estrutura aninhada repetida repete o cabeçalho [[path]] completo, o que fica mais ruidoso do que o equivalente YAML. E o TOML é mais novo e menos universal do que JSON ou YAML, então nem toda ferramenta o entende. TOML se sai melhor com configuração majoritariamente plana e um punhado de seções rotuladas, o que descreve a esmagadora maioria das configs de ferramenta.

Por que TOML para Rust e Python?

A ascensão do TOML acompanha dois ecossistemas que o adotaram como padrão. O gerenciador de pacotes do Rust, o Cargo, usa Cargo.toml para cada crate, então todo desenvolvedor Rust lê e escreve TOML desde o primeiro dia. O Python veio na sequência: a PEP 518 introduziu o pyproject.toml para declarar requisitos de build, e a PEP 621 padronizou os metadados do projeto (nome, versão, dependências e seções [tool.*]) nesse mesmo arquivo, substituindo uma dispersão de setup.py, setup.cfg e configs por ferramenta. Além desses dois, Hugo, Netlify, Poetry e Foundry usam TOML por padrão. O fio comum é config de tooling que colaboradores editam à mão e que se beneficia de ser óbvia em vez de esperta.

Frente a frente — as diferenças que realmente mordem

Uma tabela de recursos é limpa e organizada; os bugs que esses formatos causam não seguem essas linhas. Estas são as diferenças específicas que causam problemas reais, cada uma com um pequeno exemplo que você pode rodar em qualquer parser.

Comentários

JSON não tem nenhuma sintaxe de comentário. TOML e YAML ambos usam # até o fim da linha.

# TOML: um comentário no início
port = 5432  # e um comentário no fim

# YAML: estilo de comentário idêntico
port: 5432   # comentário no fim

No momento em que você cola um // ou # em JSON estrito, o parsing falha. Isso não é cosmético. Uma config que um humano mantém sem comentários acumula conhecimento tribal que vive apenas na cabeça de alguém.

Tipos de dados e datas

Os tipos do JSON são explícitos, mas escassos, sem tipo de data. Os tipos do TOML são explícitos e ricos. Os do YAML são implícitos e, como visto acima, ocasionalmente errados. Datas são a divisão mais clara. TOML expressa todos os quatro tipos nativamente:

odt = 1979-05-27T07:32:00Z   # date-time com offset (tem fuso horário)
ldt = 1979-05-27T07:32:00    # date-time local (sem fuso horário)
ld  = 1979-05-27             # date local (um dia do calendário)
lt  = 07:32:00               # time local

Converta esse TOML para JSON e cada valor vira uma string que mantém seu significado: uma date local continua "1979-05-27" em vez de ser inflada num timestamp de meia-noite falso. Nosso conversor de TOML para JSON preserva esse tipo de data exatamente, algo que muitos conversores ingênuos erram. O YAML, por sua vez, pode ou não tratar 1979-05-27 como uma data dependendo do parser e da versão do schema, que é precisamente a ambiguidade que você não quer em config de produção.

Profundidade de aninhamento

Quanto mais fundo sua config aninha, mais os formatos divergem. Pegue uma pequena árvore no estilo Docker Compose:

services:
  web:
    build:
      context: .
      args:
        NODE_ENV: production
    ports:
      - "8080:8080"

O YAML expressa profundidade com pura indentação, e ela se mantém compacta. A mesma estrutura em TOML te obriga a soletrar o caminho completo em cada cabeçalho, e a mover valores escalares para antes das tabelas filhas:

[services.web]
ports = ["8080:8080"]

[services.web.build]
context = "."

[services.web.build.args]
NODE_ENV = "production"

JSON carrega a árvore em chaves aninhadas, o que é inequívoco mas cheio de pontuação. Para config rasa os três parecem semelhantes; passando de três ou quatro níveis, o YAML é visivelmente mais enxuto e o TOML visivelmente mais repetitivo. Essa única diferença explica por que o Kubernetes escolheu YAML e o Cargo escolheu TOML.

Sensibilidade à indentação

Só o YAML se importa com espaço em branco. Em JSON e TOML você pode indentar como quiser, ou nem indentar, e o significado é idêntico. No YAML, a indentação é a estrutura, e tabs são ilegais, então um editor que insere um tab ou um bloco colado na profundidade errada silenciosamente muda o documento ou se recusa a carregar. Um item de lista indentado um espaço além pode se anexar à chave-pai errada sem erro nenhum, o que é um bug enlouquecedor de detectar a olho, porque o arquivo ainda parece razoável. Se seus colaboradores usam editores e configurações misturados, isso é um imposto permanente que o YAML cobra e os outros dois não, e é uma forte razão para rodar um linter no CI em qualquer config YAML grande.

Strings multilinha

JSON não consegue guardar uma quebra de linha literal dentro de uma string; você a escapa como \n. YAML e TOML ambos têm strings multilinha de verdade.

{ "note": "line one\nline two" }

note: |
  line one
  line two

note = """
line one
line two
"""

O | do YAML mantém as quebras de linha (um bloco > as dobra em espaços, ao invés disso), e o """ do TOML se comporta de forma parecida, aparando a quebra de linha que vem imediatamente após as aspas de abertura. Para scripts embutidos, SQL ou texto de ajuda, só isso já pode decidir o formato.

Vírgulas finais e rigidez

JSON é o mais rígido dos três. Uma vírgula final depois do último elemento de um array é um erro de sintaxe:

# TOML válido — a vírgula final está OK
ports = [
  8001,
  8002,
]

A mesma vírgula final depois de 8002 em JSON falha no parsing, e é por isso que adicionar uma linha a um array JSON tantas vezes significa também consertar a vírgula da linha de cima. TOML permite a vírgula final, e a sintaxe de lista do YAML, com um traço por linha, contorna a questão inteiramente. A rigidez é uma virtude para o intercâmbio entre máquinas e um incômodo para a edição à mão, que é o mesmo tradeoff visto do outro lado. Esse também é o atrito que JSON5 e JSONC se propuseram a remover especificamente para o JSON.

Inteiros grandes e o teto de 2^53

Todos os três formatos conseguem escrever um inteiro de 64 bits como texto. O problema começa quando esse valor passa pelo JavaScript, porque os números JSON do navegador são doubles IEEE-754 e só conseguem representar inteiros exatamente até 2^53 − 1 (9007199254740991). Um ID Snowflake ou um timestamp em nanossegundos é maior do que isso, então um round-trip por uma ferramenta baseada em JS o arredonda e corrompe o valor:

snowflake = 1420070400000000000   # exato no texto TOML

{ "snowflake": "1420070400000000000" }

A correção confiável em todos os formatos é armazenar tais valores como strings entre aspas, para que nenhum parser numérico jamais os toque. Isso não é um defeito de nenhum formato específico; é uma limitação do runtime que faz a conversão. Nossos conversores te avisam quando um inteiro cruza essa linha, em vez de corrompê-lo silenciosamente.

Como escolher — matriz de decisão e fluxograma

Quando você está de fato decidindo qual formato de config usar, percorra as perguntas em ordem e pare no primeiro “sim” forte.

1. O arquivo é escrito e lido principalmente por programas, ou o ecossistema já impõe um formato? Se sim, use JSON. Um payload de API é JSON. Um arquivo ao lado de package.json é JSON. Não brigue com o tooling.
2. Humanos editam à mão, diariamente, configuração profunda e aninhada, dentro de uma stack que espera isso (Kubernetes, CI, Ansible)? Se sim, use YAML, e adote uma convenção de aspas para desviar do problema da Noruega.
3. É config de ferramenta ou aplicação, majoritariamente plana com algumas seções, editada por colaboradores de nível variado, onde tipado e óbvio vence conciso? Se sim, use TOML.

Se duas respostas empatarem, desempate por este mapa de eixos:

Requisito	Melhor opção	Por quê
Comentários no arquivo	TOML ou YAML	JSON não tem
Valores nativos de data/hora	TOML	Quatro tipos de data explícitos
Aninhamento muito profundo	YAML	A indentação se mantém compacta
Zero surpresas com espaço em branco	JSON ou TOML	Não sensível à indentação
Preso a um arquivo do ecossistema	JSON	package.json, tsconfig.json
Edições humanas, poucas seções	TOML	Tipos explícitos, cabeçalhos tipo INI
Troca máquina a máquina	JSON	Universal, rígido, rápido
Inferência de tipo nunca pode adivinhar	JSON ou TOML	YAML infere implicitamente

A maioria dos projetos acaba usando mais de um. Um repositório pode ter um package.json JSON que ele nunca toca à mão, um pyproject.toml TOML para o seu tooling Python, workflows YAML em .github e um arquivo .env para segredos locais que não segue nenhuma dessas gramáticas. Essa mistura é normal, e é justamente o ponto: cada arquivo vive no formato que combina com quem o edita. Se a camada .env faz parte da sua configuração, nosso guia do formato de arquivo .env cobre onde ele se encaixa ao lado da config JSON e como converter entre os dois.

Convertendo entre TOML, JSON e YAML

Você acaba convertendo entre esses formatos com mais frequência do que esperaria. Um job de CI lê um pyproject.toml escrito à mão e precisa dele como JSON para alimentar um dashboard de dependências. Uma migração move um app de uma config YAML para TOML por causa da tipagem mais rígida. Uma revisão de código fica mais fácil quando você compara a forma JSON de dois arquivos em vez dos originais sensíveis a espaço em branco. Cada direção tem uma armadilha que vale conhecer antes de colar.

TOML para JSON. O principal risco são as datas. Uma date local como 1979-05-27 deveria continuar uma data de calendário, não virar um timestamp UTC de meia-noite que inventa uma hora e um fuso. Comentários também são descartados, já que JSON não consegue guardá-los. O conversor de TOML para JSON preserva cada tipo de data fielmente, de modo que os round-trips permaneçam sem perdas.

JSON para TOML. TOML é mais rígido quanto à estrutura, então duas coisas podem bloquear uma conversão. O nível superior precisa ser um objeto, porque um documento TOML é sempre uma tabela em sua raiz; um array ou escalar solto não tem para onde ir. E TOML não tem null, então um valor null de objeto é descartado (com um aviso listando quais chaves), enquanto um null dentro de um array não tem representação TOML válida nenhuma. O conversor de JSON para TOML expõe ambos os casos explicitamente em vez de produzir saída quebrada.

JSON e YAML, nas duas direções. Aqui o problema da Noruega é a coisa a observar: um NO ou 0755 sem aspas pode trocar de tipo ao cruzar a fronteira. O conversor de JSON para YAML e o conversor de YAML para JSON cuidam das aspas para que uma string continue uma string.

Depois de qualquer conversão, vale validar o resultado. Passar a saída pelo Formatador JSON confirma que o JSON está bem formado e consistentemente indentado antes de você commitá-lo ou enviá-lo adiante. E como arquivos de config carregam segredos (tokens de registry, credenciais de banco de dados, chaves de deploy), todos esses rodam inteiramente no seu navegador: nada é enviado, então um Cargo.toml com um token de registry privado ou um arquivo de values com credenciais nunca sai da sua máquina.

FAQ

TOML é melhor que YAML?

Nenhum é universalmente melhor; a escolha TOML vs YAML se resume à forma. TOML é mais difícil de errar graças aos tipos explícitos e à ausência de armadilhas de indentação, então ele vence para config de tooling majoritariamente plana. YAML expressa aninhamento profundo de forma mais compacta, então ele vence para infraestrutura grande e em camadas, como Kubernetes.

Devo usar JSON ou YAML para arquivos de configuração?

Para config que um humano edita, prefira YAML: ele permite comentários e se lê de forma limpa, o que o JSON não faz. Para config que programas geram e consomem, prefira JSON: ele é rígido, rápido e universal. A linha divisória é quem faz a edição, humano ou máquina.

Por que o JSON não permite comentários?

O criador do JSON, Douglas Crockford, removeu comentários de propósito. Ele temia que as pessoas embutissem diretivas de parsing neles e quebrassem a interoperabilidade entre parsers. Se você precisa de comentários em um arquivo com forma de JSON, use JSON5 ou JSONC, que os trazem de volta sem mudar a estrutura central.

O que é o problema da Noruega no YAML?

É o YAML 1.1 tratando certas palavras sem aspas como booleanos, então country: NO vira false em vez da string "NO". YES, ON e OFF se comportam da mesma forma. Colocar o valor entre aspas evita isso; veja o guia dedicado linkado acima para a história completa.

TOML suporta comentários?

Sim. TOML usa # para comentários, tanto em sua própria linha quanto no fim de um valor, exatamente como o YAML. Note que comentários são perdidos quando você converte TOML para JSON, já que JSON não tem sintaxe de comentário para guardá-los.

TOML consegue representar tudo o que JSON consegue?

Quase. A lacuna JSON vs TOML é pequena mas real: TOML não tem tipo null, então nulls do JSON são descartados ou rejeitados na conversão, e um documento TOML precisa ser uma tabela no nível superior, então um array ou escalar JSON solto não pode converter sem antes ser embrulhado sob uma chave.

YAML é um superconjunto de JSON?

Desde o YAML 1.2, sim: qualquer documento JSON válido também é YAML válido, então um parser YAML consegue ler JSON diretamente. É um fato útil, mas não se apoie nele como fronteira de segurança, porque parsers YAML adicionam recursos (como âncoras) que o JSON não tem.

Qual formato de config é mais rápido de parsear?

JSON é geralmente o mais rápido, com os parsers mais maduros e otimizados em toda linguagem. YAML é o mais lento e complexo de parsear por causa de sua especificação grande e da tipagem implícita. TOML fica no meio, mais perto do JSON em velocidade do que do YAML.