YAML: as armadilhas que trocam seus dados e como converter para JSON

Duas versões, dois comportamentos

O YAML 1.1 reconhece muitas palavras e formatos como tipos especiais. O YAML 1.2 restringiu isso. O problema é que bibliotecas populares ainda seguem o 1.1, como o PyYAML do Python, enquanto outras seguem o 1.2, como o pacote yaml do JavaScript. O mesmo arquivo pode ser lido de formas diferentes.

• pais: no vira false no 1.1 (o "problema da Noruega", cujo código é NO). No 1.2, continua o texto "no". O mesmo vale para yes, on e off.
• hora: 12:30 vira o número 750 no 1.1, porque ele lê números em base 60. No 1.2, é texto.
• versao: 1.10 vira o número 1.1 nas duas versões. Números de versão precisam de aspas.
• No PyYAML, a chave on: de um workflow do GitHub Actions é lida como true.

A regra prática: ponha aspas em todo texto que possa parecer outra coisa. O conversor de YAML para JSON mostra como cada valor foi entendido.

Os erros de sintaxe mais comuns

• Tabulação na indentação: o YAML só aceita espaços.
• Indentação desalinhada: um espaço a mais ou a menos muda a estrutura ou quebra o arquivo.
• Dois-pontos sem espaço depois (chave:valor): vira um texto só, não um par chave e valor.
• Texto que contém : ou começa com @, * ou crase, sem aspas.

Em JavaScript

O pacote yaml lê no padrão 1.2. Na escrita, a opção version: "1.1" põe aspas nos textos que um leitor 1.1 entenderia errado, e o resultado continua válido em 1.2. Se preferir sem código, o conversor de JSON para YAML faz a mesma conversão no navegador.

import { parse, stringify } from 'yaml'; // npm install yaml

// O pacote yaml segue o YAML 1.2: no, yes e on continuam sendo texto
function yamlParaJson(texto) {
  return JSON.stringify(parse(texto), null, 2);
}

// version '1.1' põe aspas em no, yes, 12:30 e parecidos, para que leitores
// antigos (como o PyYAML) também leiam texto como texto
function jsonParaYaml(texto) {
  return stringify(JSON.parse(texto), { version: '1.1' });
}

Em Python

Use sempre yaml.safe_load. O yaml.load com o carregador completo cria objetos Python a partir de tags no texto, o que permite executar código com um arquivo malicioso. O safe_load recusa essas tags. O PyYAML também transforma datas em objetos date, que o json.dumps não aceita sem o default=str.

import json

import yaml  # pip install pyyaml


def yaml_para_json(texto: str) -> str:
    # safe_load: o yaml.load comum pode criar objetos Python a partir do texto
    dados = yaml.safe_load(texto)
    # default=str: o PyYAML transforma 2026-01-01 em date, que o JSON não conhece
    return json.dumps(dados, indent=2, ensure_ascii=False, default=str)


def json_para_yaml(texto: str) -> str:
    return yaml.safe_dump(json.loads(texto), allow_unicode=True, sort_keys=False)

Cuidados

• Todo JSON válido é, na prática, YAML válido. Se o arquivo for gerado por programa e lido por programa, JSON evita todas essas ambiguidades.
• CEP, telefone e códigos com zero à esquerda precisam de aspas: sem elas, podem virar número e perder o zero.
• Comentários (#) somem na conversão para JSON, que não tem comentários.
• Arquivos com vários documentos separados por --- precisam de safe_load_all no Python e parseAllDocuments no JavaScript.