JSON vs YAML vs TOML, Explicado

Ultima revisao 2026-04-27. Abra o parser JSON ou JSON to CSV para trabalho JSON no navegador.

Os tres formatos lado a lado

A mesma configuracao, tres formas:

JSON                        YAML                  TOML
{                           server:               [server]
  "server": {                 host: "localhost"   host = "localhost"
    "host": "localhost",      port: 8080          port = 8080
    "port": 8080
  }
}                                                 

JSON - rigoroso e inequivoco

O objetivo de design do JSON era um formato que qualquer linguagem pudesse analisar identicamente. A gramatica e pequena (seis tipos de dados, regras de espaco em branco bem definidas). Cada parser produz a mesma arvore. Essa uniformidade e o motivo pelo qual JSON domina APIs, ficheiros de configuracao para ferramentas que trazem um parser JSON, e serializacao maquina a maquina.

Onde JSON e desajeitado: comentarios nao sao permitidos, virgulas finais sao erros de sintaxe, e configuracao profundamente aninhada fica ilegivel para humanos. A correcao e JSON5 (JSON com comentarios e virgulas finais) para configuracao editada por humanos, enquanto mantem JSON puro para transporte.

YAML - legivel, por vezes demasiado esperto

YAML le-se como notas de esquema. A indentacao cria estrutura; listas usam tracos; valores nao precisam de aspas. Os campos sao curtos e o ficheiro e denso. E por isso que YAML domina Kubernetes, GitHub Actions, Docker Compose e configuracoes de CI - todos lugares onde humanos editam o ficheiro diariamente.

Onde YAML magoa: o espaco em branco e significativo e os tabs quebram o parser. A string "yes" analisa como o booleano true. O codigo de pais Noruega "NO" analisa como false. Numeros com zeros a esquerda analisam como octal. Strings multi-linha tem quatro sintaxes diferentes. O formato e legivel por humanos mas nao seguro para humanos; bugs de analise subtis sao comuns em producao. A correcao e lintar cada ficheiro YAML em CI e citar qualquer string que pareca poder ser mal interpretada.

TOML - simples, raso

TOML mira no nicho de ficheiros de configuracao onde YAML e demasiado solto e JSON e demasiado verboso. Seccoes em parenteses retos, pares chave-valor com sinais de igual, tipos nativos de data e hora. Cargo (gestor de pacotes do Rust), pyproject.toml em Python moderno, e varias ferramentas de configuracao usam-no.

Onde TOML e desajeitado: dados profundamente aninhados. A sintaxe para arrays de tabelas e verbosa e nao visualmente obvia. Para aninhar mais de 2-3 niveis, YAML ou JSON leem melhor. TOML vence quando a configuracao e naturalmente plana - uma lista de dependencias, uma lista de definicoes de compilacao, um pequeno conjunto de seccoes nomeadas.

Regra de decisao

Maquina a maquina: JSON. Configuracao humana editada diariamente, com estrutura maioritariamente plana: TOML. Configuracao humana editada diariamente, com estrutura profundamente aninhada: YAML, com linting em CI. Em caso de duvida, JSON - o rigor e seguro barato.

Para converter entre formatos, veja JSON to CSV ou o parser JSON. Para outras ferramentas de programador, o hub de ferramentas para programadores.