Converter YAML para JSON

A indentação é a sintaxe

No JSON as chaves dizem onde uma estrutura termina. No YAML quem faz isso é a margem esquerda, e essa única decisão causa a maior parte dos erros que as pessoas encontram. Três regras que vale conhecer antes de depurar qualquer coisa:

• Tabulações são ilegais como indentação. Não desaconselhadas: proibidas pela especificação. Um editor que insere uma tabulação produz um arquivo que nenhum parser conforme vai ler, e a mensagem de erro raramente diz isso. Esta aqui diz.
• Uma sequência sob uma chave pode ficar na mesma indentação da chave. As duas formas significam a mesma coisa, o que surpreende quem vem de outros formatos: uma linha steps: seguida de traços indentados em dois espaços, e a mesma linha seguida de traços na mesma margem de steps.
• O quanto você indenta é escolha sua, mas precisa ser consistente dentro de um bloco. Dois espaços é a convenção. Misturar dois e quatro dentro de um mesmo mapeamento é onde os arquivos mudam de forma silenciosamente.

O YAML 1.2 é um superconjunto estrito do JSON, então qualquer documento JSON válido também é YAML válido. Isso é útil mais de uma vez: quando você precisa colar um fragmento em um arquivo de configuração e não quer se incomodar com a indentação.

Escalares que não são o que parecem

Valores sem aspas são resolvidos por padrão de texto, e esses padrões têm vítimas famosas. A mais conhecida é o problema da Noruega: no YAML 1.1, no é um booleano, então uma lista de países escrita como - no devolve false onde você esperava "NO". O mesmo vale para y, yes, on e off.

Vale para as chaves também, que é a versão que a maioria encontra primeiro: pelas regras de 1.1, a linha on: no topo de um workflow do GitHub Actions é o booleano verdadeiro, e não a palavra "on". Marque a caixa acima e veja isso acontecer com o exemplo.

O YAML 1.2 removeu tudo isso. Só true e false são booleanos, que é o padrão aqui. Muitos parsers reais — o carregador padrão do PyYAML entre eles — ainda se comportam como os de 1.1, então a caixa deixa você ver o arquivo do jeito que eles vão ver. Se um valor pode ser confundido com outra coisa, coloque-o entre aspas. As aspas são a solução para todas as ambiguidades desta seção.

Números têm as próprias armadilhas. version: 1.0 é o float 1, então ele volta impresso como 1 e não corresponde mais à string "1.0". 1.2.3 tem dois pontos e continua string. Zeros à esquerda são mantidos no YAML, mas o valor continua sendo um número, e no YAML 1.1 um valor como 08:30 era lido como aritmética de base 60. Um valor vazio, ~ e null significam null. Nada disso dá para adivinhar, e é por isso que arquivos de configuração que importam tendem a colocar tudo entre aspas.

Escalares de bloco

As duas partes mais úteis do YAML para as quais o JSON não tem resposta. | mantém as quebras de linha exatamente como foram escritas, que é o que você quer para um script de shell ou um certificado embutido. > dobra as linhas em um parágrafo, juntando-as com espaços, que é o que você quer para uma descrição longa. Os dois removem a indentação comum, então o texto não carrega o layout do seu arquivo para dentro do valor.

O caractere final controla o que acontece com a última quebra de linha. | sozinho mantém exatamente uma, |- não mantém nenhuma e |+ mantém todas as linhas em branco do fim. Essa distinção importa mais do que parece: uma chave com uma quebra de linha final acidental é uma causa comum de uma assinatura ou de um token falhar na validação.

O que este conversor recusa

Ele cobre mapeamentos de bloco, sequências de bloco, coleções de fluxo, comentários, aspas, escalares de bloco, escalares simples dobrados e os tipos escalares básicos. Ele para nos recursos que não dá para representar com honestidade:

• Âncoras e aliases (&base e *base) e chaves de mesclagem (<<). Elas duplicam ou compartilham estrutura, e expandi-las muda o sentido do documento de formas que você deve decidir, e não uma página web.
• Tags como !!str ou tags próprias de uma aplicação. O JSON não tem anotações de tipo para colocá-las.
• Vários documentos. Só o primeiro é convertido, e você fica sabendo quantos havia.
• Chaves complexas (a sintaxe ? key) e chaves que não são strings. Os nomes de objeto do JSON são strings, então 1: one vira "1": "one".

Cada um desses casos gera um erro com número de linha em vez de produzir um resultado de aparência plausível. Esse é o compromisso deliberado: um conversor que descarta uma âncora silenciosamente é pior do que um que para.

Mais duas coisas para saber. Os números passam pelo JavaScript, então um inteiro acima de 9.007.199.254.740.991 perde precisão no caminho — coloque IDs longos entre aspas. E .inf e .nan ficam como as strings que foram escritas, porque o JSON não tem como escrever nenhum dos dois.

Uma coisa você ganha de graça: este parser só produz dados simples. Algumas bibliotecas de YAML em outras linguagens conseguem construir objetos arbitrários a partir de uma tag no arquivo, e é por isso que carregar YAML não confiável com a função errada já foi uma fonte real de execução remota de código. Aqui nada pode fazer mais do que construir strings, números, arrays e objetos.

Última atualização 19 de setembro de 2026