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

> O YAML parece simples, mas alguns leitores transformam texto em outro tipo sem avisar: no vira false, 12:30 vira 750 e 1.10 vira 1.1. Este guia explica de onde vêm essas trocas (as versões 1.1 e 1.2 do YAML), como escrever YAML que qualquer leitor entende e como converter entre YAML e JSON em JavaScript e Python com segurança.

- Endereço oficial: https://pradev.com.br/guias/yaml-armadilhas-e-conversao-para-json
- Tipo: Guia
- Publicado em: 2026-09-30
- Atualizado em: 2026-09-30
- Autor: Leonardo Gaertner (https://pradev.com.br/sobre)
- Ferramentas: [Conversor YAML para JSON](https://pradev.com.br/conversor-yaml-para-json), [Conversor JSON para YAML](https://pradev.com.br/conversor-json-para-yaml)

## 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](https://pradev.com.br/conversor-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](https://pradev.com.br/conversor-json-para-yaml) faz a mesma conversão no navegador.

```javascript
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' });
}
```

_JavaScript. Precisa do pacote yaml (npm install yaml)._

## 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`.

```python
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)
```

_Python. Precisa do PyYAML (pip install pyyaml). Ele segue o YAML 1.1: no vira 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.

## Perguntas frequentes

### Por que no virou false no meu YAML?

O leitor segue o YAML 1.1, em que no, yes, on e off são booleanos. O PyYAML, por exemplo, faz isso. Ponha aspas no valor ("no") para ele ser sempre texto.

### YAML aceita tabulação?

Não na indentação. O YAML só aceita espaços para indentar, e uma tabulação faz o arquivo ser recusado. Configure o editor para inserir espaços em arquivos .yml e .yaml.

### yaml.load ou yaml.safe_load?

safe_load. O yaml.load com o carregador completo pode criar objetos Python arbitrários a partir do texto, o que é um risco de segurança com arquivos de fora. O safe_load só cria tipos simples.

### Todo JSON é YAML válido?

Na prática, sim: o YAML 1.2 foi ajustado para aceitar JSON. Por isso um arquivo JSON costuma funcionar onde se espera YAML.

## Fontes

- [Especificação YAML 1.2.2](https://yaml.org/spec/1.2.2/)
- [Documentação do PyYAML](https://pyyaml.org/wiki/PyYAMLDocumentation)

## Guias relacionados

- [Como formatar e validar JSON em JavaScript, Python e PHP](https://pradev.com.br/guias/como-formatar-e-validar-json): Como deixar JSON legível e descobrir o erro de um JSON inválido em JavaScript, Python e PHP, com os erros mais comuns e as diferenças entre as linguagens.