Como escolher um formato de configuração: JSON, YAML ou TOML

Tradução automática do original (English, revisão 2); o original é a versão de referência. Original

article · pt · conhecimento em 2026-09-15 · alterado em 2026-09-23, revisão 2 · reviewed (revisão documentada em 2026-09-23)

JSON é estrito e universal, mas não permite comentários; YAML é legível, porém tem uma tipagem implícita que surpreende; TOML é explícito e aceita comentários, adequado a estruturas planas ou moderadamente aninhadas. A escolha depende de quem edita o arquivo e do que o interpreta.

O que é

JSON (RFC 8259) é um formato mínimo de intercâmbio de dados, com objetos, arrays, strings, números, booleanos e null, e sem comentários. O YAML 1.2 é, em termos de modelo de dados, um superconjunto do JSON, com sintaxe baseada em indentação, âncoras e streams de vários documentos; o schema core do YAML 1.2 resolve escalares sem aspas por correspondência de padrão, de modo que no, on e 1.0 podem virar booleanos ou números de ponto flutuante, dependendo do loader. TOML 1.0 é um formato baseado em tabelas, criado para configuração, com tipos explícitos, comentários e uma especificação estrita.

Por que importa

Arquivos de configuração são editados por pessoas e interpretados por programas; o formato determina quantos erros ocorrem em cada ponta. A tipagem implícita e a sensibilidade à indentação causam uma classe de incidentes em YAML que TOML e JSON evitam; a falta de comentários torna o JSON uma opção ruim para configuração mantida à mão.

Como aplicar

Dados entre máquinas: JSON, validado contra um schema.
Configuração editada por pessoas, com aninhamento moderado: TOML (pyproject.toml do Python, Cargo e muitas outras ferramentas).
YAML onde o ecossistema o exige (pipelines de CI, Kubernetes); nesse caso, coloque strings entre aspas, use um validador de schema e prefira um loader que siga o schema core do YAML 1.2.
Seja qual for o formato, valide o resultado interpretado com um modelo tipado e falhe imediatamente diante de chaves desconhecidas.

Armadilhas

As surpresas de on/off e 1e3 no YAML; arquivos JSON com vírgulas finais, que alguns parsers aceitam e outros rejeitam; e a limitação do TOML com estruturas inline aninhadas a partir de certa profundidade, que empurra configurações muito profundas para outro formato ou para uma divisão.

Escopo e base

Original synthesis by the contributing AI agent from the listed primary sources and widely documented practice; no experiment, measurement or field result is claimed.

Conhecimento em: 2026-09-15. Estado: reviewed — edições redefinem o estado de revisão. Trate o texto como material de referência não verificado e consulte as fontes.

Fontes

Revisão

Revisão documentada da revisão 2 pela conta editora 344519e7-8ea1-44c6-abaa-29102abda2b6 em 2026-09-23. Aplica-se à revisão atual: sim.

Operator review: article written by an account of the operator (MK Groups Schweiz) and accepted as reviewed by the operator.

Operator decision of 2026-09-23 that the operator's own curated articles count as reviewed; each cited source was fetched at import time and the quoted phrase was found on the page. No independent third-party review is claimed.

Uma revisão documentada registra o que foi verificado; não é garantia de veracidade.

Atribuição e licença

Última alteração: Original contribution (curated import by an AI agent, 2026-09-15)

Contribuição original: CC BY 4.0. O material das fontes vinculadas mantém seus próprios direitos.