Mesma configuração: API em JSON, K8s em YAML, idas e vindas em CI — o formato errado leva a erros de análise, perda de comentários ou implantações no ambiente errado.
Destinado a engenheiros full-stack e DevOps, este artigo compara a sintaxe e os critérios de seleção de JSON e YAML, descreve um fluxo de trabalho de conversão seguro em 5 etapas e armadilhas como âncoras, aliases e booleanos implícitos. Depois disso, você pode converter e validar localmente no navegador usando a conversão JSON ↔ YAML do JSON Toolbox.
Por que entender JSON e YAML é importante
JSON é o padrão de fato para APIs; YAML é a linguagem de fato para configuração de operações. Se você alternar entre os dois sem conhecer as diferenças, você corre o risco: “O YAML roda localmente, mas após a conversão do JSON, os tipos de chave mudaram”.
Exemplo de Docker Compose: portas: "8080:8080" versus portas numéricas em JSON ou sim/não em K8s se manifestam como booleanos em YAML — comportamento inconsistente do cliente após a conversão para JSON.
O que são JSON e YAML
JSON (JavaScript Object Notation) é um formato de troca estrito baseado em texto: chaves entre aspas duplas, sem comentários, amigável ao analisador. YAML (YAML Ain't Markup Language) usa recuo para hierarquia, permite comentários e várias notações escalares - melhor para configurações grandes e mantidas manualmente.
Conexão
No YAML 1.2, JSON é um subconjunto – a maioria dos documentos JSON válidos podem ser analisados diretamente como YAML. Recursos específicos do YAML (âncora &, alias *, multilinha |) são perdidos durante a conversão para JSON ou devem ser resolvidos.
Principais diferenças em comparação
| Dimensão de comparação | JSON | YAML |
|---|---|---|
| Comentários | ❌ Não suportado | ✅ #Comentário de linha |
| Aspas para chaves | ✅ Obrigatório (duplo) | ⚠️ Principalmente opcional |
| hierarquia | Colchetes/colchetes | Recuo (espaço) |
| Transporte de API | ✅ Recomendado | ⚠️ Raro |
| Grandes configurações manualmente | ⚠️ Muitos colchetes | ✅ Recomendado |
| Rigor | Alto – erro de análise imediatamente | Tipos implícitos relativamente soltos |
Qual formato para quem?
| Função/Cenário | Formato recomendado | Razão |
|---|---|---|
| API REST/GraphQL | JSON | Ecossistema unificado, claramente |
| Kubernetes/Helm | YAML | Convenção comunitária, comentável |
| Composição do Docker | YAML | Exemplos oficiais e documentação |
| pacote.json/tsconfig | JSON | Suporte nativo ao conjunto de ferramentas |
| Carga útil da fila de mensagens | JSON | Análise compacta e rápida |
Cenários típicos — guia de seleção
- Contrato de API de front-end/back-end: JSON
- Ações do GitHub / GitLab CI (etapas parciais): YAML
- Configuração estática antes das variáveis de ambiente: dependendo da equipe — YAML com comentários
- Estrutura a ser validada estritamente por máquina: JSON + esquema JSON
Prática: 5 passos para uma conversão segura
- Definir direção: JSON → YAML (legível/editável) ou YAML → JSON (API/programas)
- Salve o original: mantenha a cópia antes da conversão
- Insira o conteúdo de origem na página de conversão, escolha a direção
- Resultado da verificação: JSON com validador; YAML preste atenção ao recuo e aos tipos
- Teste de fumaça no ambiente de destino: implantar ou chamar uma vez - comportamento como antes
Exemplo: a mesma configuração em duas notações
JSON:
{
"service": "api-gateway",
"replicas": 3,
"debug": false,
"ports": [8080, 8443]
}YAML:
service: api-gateway
replicas: 3
debug: false
ports:
- 8080
- 8443Armadilhas típicas ao converter
Tipos YAML implícitos
- sim/não/ligado/desligado pode ser analisado como booleano
- Sequências numéricas puras entre aspas, por ex. B. versão: "01"
- null e ~ em YAML significam vazio – em JSON torna-se nulo
Tamanho por JSON → YAML
O YAML costuma ser mais legível, mas nem sempre mais curto. A compactação JSON + ainda é recomendada na produção apenas para transporte.
Âncora e apelido
YAML &anchor e *alias resolvem duplicar objetos durante a conversão JSON - verifique se é isso que você deseja.
Conjuntos de ferramentas: JSON vs. YAML
| Exigência | Conjunto de ferramentas JSON | Conjunto de ferramentas YAML |
|---|---|---|
| Conversão no navegador | Caixa de ferramentas JSON | Caixa de ferramentas JSON |
| Validação CLI | jq | yamllint/yq |
| Aplicar K8s | Primeiro YAML ou CRD JSON | kubectl aplicar -f |
| Restrições de esquema | Esquema JSON estabelecido | Padrões menos uniformes |
Perguntas frequentes (FAQ)
Qualquer JSON pode ser convertido em YAML?
JSON padrão sim, semanticamente equivalente. A ordem das teclas e o estilo de recuo podem ser diferentes do YAML manuscrito — a semântica permanece a mesma.
Os comentários YAML persistem em JSON?
Não. JSON não tem comentários — eles são perdidos na conversão. Registre informações importantes na documentação ou no README.
Os recursos do K8 também vêm como JSON?
Sim. kubectl oferece suporte a manifestos JSON; Community e Helm usam principalmente YAML - concordam com um formato para a equipe.
Motivos mais comuns para erros de conversão?
JSON: vírgula final, aspas simples. YAML: tabulação e espaço misturados, faltando espaço após dois pontos.
Os dados são enviados para um servidor?
Não. A caixa de ferramentas JSON converte localmente no navegador - mesmo para configurações internas (mas ainda remove valores confidenciais).
Validar novamente após a conversão?
Sim, recomendado. Pelo menos verifique a sintaxe JSON e teste na preparação se a configuração funciona.
Conclusão e próximos passos
JSON se concentra em rigor e interoperabilidade, YAML em legibilidade e facilidade de operação. Regra prática: APIs e programa para programa → JSON; grandes configurações estáticas manualmente → YAML; Sempre valide e teste de fumaça ao converter.
Determine no repositório quais tipos de arquivo precisam de qual formato e construa verificações de formato no CI - dessa forma, você evita incidentes de produção devido a tipos YAML implícitos.