Conversão de JSON para YAML: Um Guia Completo de Migração

O JSON e o YAML representam as mesmas estruturas de dados com sintaxe diferente. A conversão entre eles é simples na maioria dos casos, mas casos extremos relacionados com tipos, strings multilinha e comentários requerem atenção. Este guia abrange o mapeamento completo entre os formatos.

Mapeamento de Sintaxe

Objetos / Mapeamentos

JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  }
}

YAML:

database:
  host: localhost
  port: 5432
  name: myapp

Arrays / Sequências

JSON:

{
  "servers": ["web1", "web2", "web3"]
}

YAML:

servers:
  - web1
  - web2
  - web3

Estruturas Aninhadas

JSON:

{
  "services": [
    {
      "name": "api",
      "ports": [8080, 8443],
      "env": {"NODE_ENV": "production"}
    }
  ]
}

YAML:

services:
  - name: api
    ports:
      - 8080
      - 8443
    env:
      NODE_ENV: production

Converta instantaneamente com o nosso conversor de JSON para YAML.

Casos Extremos a Ter em Atenção

1. Comentários

O YAML suporta comentários; o JSON não. Ao converter YAML para JSON, todos os comentários são perdidos:

# Este comentário será perdido em JSON
database:
  host: localhost  # Também perdido

2. Strings Multilinha

O YAML tem uma sintaxe multilinha poderosa que o JSON não possui:

description: |
  This is a multi-line
  string that preserves
  line breaks.

Em JSON, isto torna-se:

{
  "description": "This is a multi-line\nstring that preserves\nline breaks.\n"
}

3. Ambiguidade de Tipos

O YAML deteta tipos automaticamente, o que pode causar problemas:

version: 1.0    # Float, não string "1.0"
port: 080       # Octal 64, não string "080"
country: NO     # Booleano false, não string "NO"

Em JSON, os tipos são explícitos:

{
  "version": "1.0",
  "port": "080",
  "country": "NO"
}

Ao converter JSON para YAML, adicione aspas em torno de valores que possam ser mal interpretados.

4. Valores Nulos

Ambos suportam null, mas a sintaxe difere:

value: null     # Explícito
value: ~        # Abreviatura YAML
value:          # Valor vazio = null

{ "value": null }

5. Caracteres Especiais em Chaves

As chaves JSON podem conter qualquer caractere unicode. As chaves YAML com caracteres especiais necessitam de aspas:

"content-type": "application/json"  # Hífen necessita de aspas
simple_key: value                    # Underscore está correto

Conversão na Linha de Comandos

Utilizar yq (processador YAML)

# JSON para YAML
yq -P input.json > output.yaml

# YAML para JSON
yq -o=json input.yaml > output.json

Utilizar Python

# JSON para YAML
python3 -c "import json, yaml, sys; print(yaml.dump(json.load(sys.stdin), default_flow_style=False))" < input.json > output.yaml

# YAML para JSON
python3 -c "import json, yaml, sys; print(json.dumps(yaml.safe_load(sys.stdin), indent=2))" < input.yaml > output.json

Utilizar jq + yq em conjunto

# Processar JSON, produzir como YAML
cat config.json | jq '.database' | yq -P

Quando Utilizar Cada Formato

Utilizar JSON para: Comunicação com APIs, armazenamento de dados, configurações geradas por máquina, ambientes de navegador.

Utilizar YAML para: Configurações editadas por humanos, Docker Compose, Kubernetes, pipelines de CI/CD, Ansible.

Para uma comparação mais aprofundada, consulte o nosso artigo YAML vs JSON.

FAQ

O YAML é um superconjunto de JSON?

Sim, desde o YAML 1.2 (2009), todo documento JSON válido é também YAML válido. Um parser YAML pode analisar JSON diretamente. No entanto, o inverso não é verdade — funcionalidades do YAML como comentários, âncoras e strings multilinha não têm equivalente em JSON.

Qual é mais rápido de analisar, JSON ou YAML?

O JSON é significativamente mais rápido de analisar em praticamente todas as linguagens. Os parsers JSON são mais simples porque o formato tem menos sintaxe para tratar. Para ficheiros de configuração carregados uma vez no arranque, a diferença é negligenciável. Para processamento de dados de alto throughput, o JSON é a escolha clara.

Recursos Relacionados

• Conversor de JSON para YAML — Converter entre formatos instantaneamente
• YAML vs JSON — Comparação detalhada de formatos
• Tutorial de Sintaxe YAML — Aprender YAML do zero