Bellacosa Mainframe e o yaml na pratica e sem misterios

☕ Um Café no Bellacosa Mainframe

YAML na Prática sem Mistérios

O guia do Programador COBOL Padawan para dominar configurações, automação e infraestrutura sem provocar um ABEND na indentação

Imagine a seguinte cena.

Você passou anos navegando pelos corredores seguros do IBM Z. Conhece JCL, COBOL, CICS, Db2, VSAM, SDSF, RACF e talvez até tenha algumas cicatrizes de batalhas contra um S0C7 ocorrido às três da manhã.

Então, certo dia, alguém da equipe DevOps aparece e diz:

— Precisamos alterar o arquivo YAML do pipeline.

Você olha para a tela e encontra algo parecido com isto:

aplicacao:
  nome: CONTAS
  linguagem: COBOL
  ambiente: homologacao

Não há IDENTIFICATION DIVISION.

Não há ponto final obrigatório.

Não há colunas 7, 8 ou 72.

Não há //SYSIN DD *.

Mesmo assim, aqueles espaços aparentemente inocentes controlam aplicações, pipelines, containers, provisionamento de infraestrutura e processos automatizados.

Bem-vindo ao universo do YAML.

Para o programador mainframe, aprender YAML não significa abandonar COBOL, JCL ou o IBM Z. Significa construir uma ponte entre o processamento corporativo tradicional e o mundo de automação, APIs, Git, CI/CD, Ansible, Kubernetes, z/OSMF, Zowe e infraestrutura como código.

O YAML pode parecer simples, mas possui uma regra implacável:

A máquina não enxerga beleza estética. Ela enxerga estrutura.

Um espaço colocado no lugar errado pode alterar completamente o significado do documento.

Pegue sua caneca de café, ajuste os sensores da Enterprise e prepare-se. Vamos explorar YAML do básico ao laboratório prático.

1. Afinal, o que é YAML?

YAML é uma linguagem de serialização de dados legível por humanos, muito utilizada para representar configurações e estruturas de informação.

A versão oficial da especificação é a YAML 1.2.2, publicada para corrigir erros e esclarecer pontos da versão 1.2, sem introduzir mudanças normativas fundamentais.

Serializar dados significa representar informações estruturadas em um formato que possa ser:

gravado em arquivo;
transmitido entre sistemas;
interpretado por programas;
armazenado em repositórios;
usado para configurar ferramentas;
convertido para objetos em diferentes linguagens.

A sigla YAML significa:

YAML Ain’t Markup Language

Ou, em português:

YAML não é uma linguagem de marcação.

Trata-se de um acrônimo recursivo, uma brincadeira clássica da cultura da computação.

Isso procura deixar claro que YAML não foi criado para formatar páginas como HTML. Seu objetivo principal é representar dados.

Um arquivo YAML pode descrever:

servidores;
aplicações;
ambientes;
parâmetros de execução;
pipelines;
inventários;
jobs;
containers;
permissões;
tarefas de automação;
configurações de testes;
serviços e dependências.

No universo mainframe, ele pode representar:

nomes de datasets;
subsistemas CICS;
regiões IMS;
bibliotecas de carga;
parâmetros de compilação;
aplicações COBOL;
ambientes de desenvolvimento;
comandos TSO;
tarefas do Ansible;
definições de pipelines;
informações de deploy;
configurações do Zowe;
chamadas ao z/OSMF;
propriedades usadas pelo IBM Dependency Based Build.

2. YAML não é uma linguagem de programação

Esse ponto é essencial.

YAML não possui, por si só:

comandos executáveis;
estruturas de repetição;
processamento de arquivos;
cálculos;
acesso a banco de dados;
chamadas de subprogramas;
controle transacional;
gerenciamento de memória.

Ele apenas descreve dados.

Considere:

programa:
  nome: PGMPAG01
  linguagem: COBOL
  compilacao: obrigatoria

Esse documento não compila o programa.

Ele apenas declara informações.

Outra ferramenta poderá ler esse arquivo e decidir:

localizar o fonte PGMPAG01;
executar uma compilação;
realizar o bind do programa;
publicar o módulo de carga;
iniciar os testes.

Portanto, pense no YAML como um SYSIN moderno e estruturado.

No mainframe, é comum entregar parâmetros para um utilitário:

//SYSIN DD *
  DELETE CLIENTES
  DEFINE CLUSTER(...)
  LISTCAT
/*

No mundo da automação, uma ferramenta pode receber parâmetros em YAML:

operacao: criar
dataset: USER01.TESTE.COBOL
tipo: biblioteca
formato:
  recfm: FB
  lrecl: 80

O princípio é parecido:

O arquivo descreve o que desejamos. Outra ferramenta interpreta e executa.

3. Onde um mainframer encontrará YAML?

YAML aparece com frequência crescente na modernização do IBM Z.

Ansible

Playbooks do Ansible são normalmente escritos em YAML.

- name: Verificar datasets
  hosts: zos
  tasks:
    - name: Consultar biblioteca COBOL
      ibm.ibm_zos_core.zos_data_set:
        name: USER01.COBOL
        state: present

Pipelines de CI/CD

GitHub Actions, GitLab CI, Azure DevOps e outras plataformas usam YAML para descrever pipelines.

jobs:
  compilar:
    steps:
      - name: Compilar COBOL
        run: python compilar.py

Kubernetes

Objetos como pods, deployments, services e configurações são frequentemente declarados em YAML.

Zowe

Arquivos de perfil e configurações de ferramentas do ecossistema Zowe podem envolver estruturas YAML.

IBM Dependency Based Build

Configurações de build e processos de automação podem utilizar YAML direta ou indiretamente, dependendo da arquitetura adotada.

Testes automatizados

Ferramentas podem usar YAML para definir:

massa de testes;
valores de entrada;
resultados esperados;
ambientes;
parâmetros de conexão.

Infraestrutura como código

YAML também aparece em ferramentas que provisionam, configuram ou descrevem ambientes de infraestrutura.

Por isso, conhecer YAML é como aprender a interpretar painéis de uma nave moderna. Você talvez não tenha construído o motor de dobra, mas precisa entender os controles.

4. O primeiro segredo: YAML é uma árvore

Um arquivo YAML deve ser imaginado como uma árvore hierárquica.

Veja:

aplicacao:
  nome: PAGAMENTOS
  plataforma: IBM Z
  componentes:
    - COBOL
    - CICS
    - Db2

A raiz possui uma chave chamada aplicacao.

Dentro dela existem:

nome;
plataforma;
componentes.

E componentes contém uma lista.

Podemos imaginar:

aplicacao
├── nome
├── plataforma
└── componentes
    ├── COBOL
    ├── CICS
    └── Db2

Essa visão ajuda muito o programador COBOL.

Pense em uma estrutura semelhante a uma área de dados:

01 WS-APLICACAO.
   05 WS-NOME          PIC X(20).
   05 WS-PLATAFORMA    PIC X(10).
   05 WS-COMPONENTES.
      10 WS-COMPONENTE OCCURS 3 TIMES PIC X(10).

Não é uma correspondência perfeita, mas a analogia é excelente para começar.

5. Os componentes fundamentais

5.1 Chave e valor

A estrutura mais comum é:

chave: valor

Exemplo:

programa: PGMCAD01
linguagem: COBOL

O espaço depois dos dois-pontos é importante.

Prefira:

programa: PGMCAD01

Evite:

programa:PGMCAD01

5.2 Mapas

Um mapa agrupa pares de chave e valor.

programa:
  nome: PGMCAD01
  tipo: batch
  linguagem: COBOL

programa contém um mapa com três propriedades.

Em COBOL, isso lembra um grupo de nível 01 com campos subordinados.

5.3 Listas

As listas são indicadas por hífens:

bibliotecas:
  - USER01.COBOL
  - USER01.COPYBOOK
  - USER01.JCL

Isso se aproxima conceitualmente de uma tabela OCCURS.

05 WS-BIBLIOTECA OCCURS 3 TIMES PIC X(44).

5.4 Lista de objetos

Podemos ter vários elementos complexos:

programas:
  - nome: PGMCAD01
    tipo: batch
    linguagem: COBOL

  - nome: PGMCIC01
    tipo: online
    linguagem: COBOL

Cada item da lista possui suas próprias propriedades.

5.5 Booleanos

ativo: true
compilar: false

Para arquivos modernos, prefira true e false.

Evite depender de palavras como yes, no, on e off, pois bibliotecas baseadas em versões ou esquemas diferentes do YAML podem tratá-las de formas distintas.

Quando houver dúvida sobre o tipo, use aspas:

resposta: "yes"
estado: "on"

5.6 Números

timeout: 30
quantidade_retentida: 10
percentual: 99.5

5.7 Valores nulos

responsavel: null

Isso representa ausência de valor.

5.8 Comentários

# Aplicação responsável pelo cadastro de clientes
aplicacao: CLIENTES

Comentários começam com #.

Eles são úteis, mas não devem substituir uma documentação adequada.

6. A Lei Suprema da Indentação

Em COBOL tradicional, a coluna sempre teve grande importância.

YAML também é profundamente sensível ao posicionamento, porém usa indentação para representar hierarquia.

Observe:

aplicacao:
  nome: FATURAMENTO
  ambiente: producao

Os campos nome e ambiente pertencem a aplicacao.

Agora veja:

aplicacao:
  nome: FATURAMENTO
ambiente: producao

Aqui, ambiente não pertence mais a aplicacao. Ele está no nível principal do documento.

O arquivo pode continuar sintaticamente válido, mas seu significado mudou.

Esse é um dos erros mais perigosos em YAML: o documento pode ser aceito pelo parser, mas representar outra estrutura.

Nunca use TAB para indentar

Use espaços.

A especificação do YAML trabalha com espaços na indentação, não com caracteres de tabulação.

Uma convenção segura é usar dois espaços por nível:

aplicacao:
  banco:
    nome: DB2P
    tabelas:
      - CLIENTES
      - CONTAS

Não existe obrigação universal de usar exatamente dois espaços, mas a consistência é obrigatória.

É como trabalhar com níveis COBOL:

01 REGISTRO.
   05 CLIENTE.
      10 NOME.
      10 CONTA.

O nível informa a estrutura. No YAML, a indentação cumpre esse papel.

7. Aspas: quando usar?

Muitos valores não precisam de aspas:

nome: FATURAMENTO
ambiente: producao

Entretanto, há situações nas quais as aspas evitam ambiguidades.

Strings que parecem números

codigo: "00123"

Sem aspas, um parser poderá tratar o valor como número e perder os zeros à esquerda.

Para um mainframer, isso é crítico. 00123 pode ser um código, não o número cento e vinte e três.

Datas

data_processamento: "2026-07-18"

Colocar datas entre aspas impede que determinadas bibliotecas façam conversões automáticas inesperadas.

Valores com caracteres especiais

descricao: "Processamento: fechamento mensal"

Valores semelhantes a booleanos

estado: "on"
resposta: "no"

Senhas ou tokens

Mesmo usando aspas, não grave segredos diretamente no YAML:

senha: "MinhaSenhaSecreta"

Isso continua sendo texto visível.

Aspas não criptografam.

O correto é usar:

gerenciadores de segredos;
variáveis de ambiente;
cofres de credenciais;
mecanismos protegidos pelo pipeline;
soluções corporativas integradas ao RACF ou à plataforma utilizada.

8. Textos com várias linhas

YAML possui recursos muito úteis para textos longos.

Preservando as quebras de linha com `|`

descricao: |
  Este processo executa o fechamento diário.
  Em caso de falha, consulte o runbook.
  Não reinicie sem verificar o checkpoint.

O | preserva as quebras de linha.

Dobrando as linhas com `>`

descricao: >
  Este processo executa o fechamento diário
  e deve ser acompanhado pela equipe
  responsável pela aplicação.

O > normalmente transforma as quebras em espaços, formando um parágrafo.

Isso pode ser útil para:

descrições;
comandos;
mensagens;
procedimentos operacionais;
instruções de deploy.

9. Laboratório no Windows

Vamos montar um ambiente prático.

Precisaremos de:

Windows 10 ou Windows 11;
Visual Studio Code;
extensão YAML;
Python;
biblioteca PyYAML;
Prompt de Comando ou PowerShell.

A documentação oficial do Python informa que o gerenciador de instalação para Windows pode ser obtido pela Microsoft Store ou pelos canais oficiais do Python.

A extensão YAML da Red Hat para Visual Studio Code oferece recursos como validação, detecção de erros, conclusão automática, visão estrutural do documento e suporte a esquemas.

Passo 1 — Criar a pasta do projeto

Abra o Prompt de Comando:

mkdir C:\yaml-mainframe
cd C:\yaml-mainframe

Essa será nossa USS local — uma pequena base de operações no Windows.

Passo 2 — Verificar o Python

Execute:

python --version

Em instalações mais novas do Windows, também poderá funcionar:

py --version

Depois, confirme o gerenciador de pacotes:

py -m pip --version

Passo 3 — Criar um ambiente virtual

No diretório do projeto:

py -m venv .venv

Ative o ambiente no Prompt de Comando:

.venv\Scripts\activate

No PowerShell:

.\.venv\Scripts\Activate.ps1

Quando o ambiente estiver ativo, o terminal normalmente exibirá algo semelhante a:

(.venv) C:\yaml-mainframe>

O ambiente virtual isola as dependências do projeto. Isso evita instalar bibliotecas globalmente sem necessidade.

Passo 4 — Instalar o PyYAML

python -m pip install pyyaml

PyYAML é uma biblioteca para ler e gerar YAML usando Python, e sua instalação pode ser realizada por meio do pip.

Passo 5 — Abrir o projeto no Visual Studio Code

code .

Caso o comando code não esteja disponível, abra o VS Code manualmente e selecione:

Arquivo → Abrir Pasta → C:\yaml-mainframe

Passo 6 — Instalar a extensão YAML

No VS Code:

abra a área de extensões;
pesquise por YAML;
selecione a extensão publicada pela Red Hat;
clique em instalar.

Agora teremos realce de sintaxe e auxílio na identificação de erros.

10. Nosso projeto: inventário de aplicações mainframe

Crie o arquivo:

inventario-mainframe.yaml

Digite:

---
empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe

zos:
  sistema: ZOS1
  versao: "3.1"
  sysplex: BELLAPLEX
  lpar: ZHML01

subsistemas:
  cics:
    ativo: true
    regioes:
      - nome: CICSHML1
        tipo: AOR
        porta: 30101

      - nome: CICSHML2
        tipo: TOR
        porta: 30102

  db2:
    ativo: true
    subsistema: DB2H
    versao: "13"
    databases:
      - CLIENTES
      - CONTAS
      - PAGAMENTOS

aplicacoes:
  - nome: CADASTRO-CLIENTES
    codigo: "APL001"
    tipo: online
    linguagem: COBOL
    transacao_cics: CCLI
    programa_principal: PGMCIC01
    bibliotecas:
      fonte: USER01.COBOL
      copybook: USER01.COPYLIB
      carga: USER01.LOAD
    dependencias:
      - Db2
      - CICS
      - VSAM
    compilacao:
      obrigatoria: true
      compilador: Enterprise COBOL
      opcoes:
        - RENT
        - SSRANGE
        - TEST

  - nome: FECHAMENTO-DIARIO
    codigo: "APL002"
    tipo: batch
    linguagem: COBOL
    programa_principal: PGMFEC01
    jcl: JOBFEC01
    bibliotecas:
      fonte: USER01.BATCH.COBOL
      copybook: USER01.COPYLIB
      carga: USER01.BATCH.LOAD
    dependencias:
      - Db2
      - DFSORT
    janela:
      inicio: "22:00"
      termino: "23:30"
    compilacao:
      obrigatoria: false
      compilador: Enterprise COBOL
      opcoes:
        - RENT
        - OPTFILE

politicas:
  permitir_deploy_manual: false
  exigir_aprovacao: true
  reter_backups: 10

mensagem_operacional: |
  Antes de executar qualquer deploy:
  1. verificar o resultado da compilação;
  2. conferir os testes automatizados;
  3. validar o plano de retorno;
  4. consultar o responsável pela mudança.

easter_egg:
  nave: USS Enterprise
  computador: LCARS-Z
  mensagem: "A lógica é apenas o começo da sabedoria."
...

Agora vamos entender o documento.

11. Explicando cada parte

Marcador inicial

---

Os três hífens indicam o início de um documento YAML.

Não são sempre obrigatórios, mas tornam o arquivo mais explícito, especialmente quando existe mais de um documento no mesmo fluxo.

Informações gerais

empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe

São propriedades simples no nível raiz.

Estrutura do z/OS

zos:
  sistema: ZOS1
  versao: "3.1"

zos é um mapa.

A versão foi colocada entre aspas para preservar seu significado como identificador textual, não como número para cálculos.

Subsistemas

subsistemas:
  cics:
  db2:

Temos um mapa chamado subsistemas, contendo outros mapas.

Regiões CICS

regioes:
  - nome: CICSHML1
    tipo: AOR

regioes é uma lista.

Cada item possui:

nome;
tipo;
porta.

Aplicações

aplicacoes:
  - nome: CADASTRO-CLIENTES

aplicacoes é uma lista de objetos complexos.

Cada aplicação contém propriedades próprias.

Bibliotecas

bibliotecas:
  fonte: USER01.COBOL
  copybook: USER01.COPYLIB
  carga: USER01.LOAD

Aqui usamos um mapa porque cada biblioteca possui uma função diferente.

Dependências

dependencias:
  - Db2
  - CICS
  - VSAM

É uma lista simples.

Opções de compilação

opcoes:
  - RENT
  - SSRANGE
  - TEST

Outro exemplo de lista.

Não estamos executando o compilador. Estamos documentando ou parametrizando quais opções uma automação deverá usar.

Mensagem operacional

mensagem_operacional: |

O símbolo | preserva as linhas, criando um pequeno runbook dentro do arquivo.

Final do documento

...

Os três pontos podem indicar o encerramento explícito do documento.

Assim como ---, são opcionais em muitos casos.

12. Criando o programa Python que lerá o YAML

Crie o arquivo:

ler_inventario.py

Digite:

from pathlib import Path
import sys

import yaml


ARQUIVO_YAML = Path("inventario-mainframe.yaml")


def carregar_yaml(caminho: Path) -> dict:
    """Carrega um arquivo YAML com tratamento básico de erros."""

    if not caminho.exists():
        raise FileNotFoundError(
            f"O arquivo {caminho} não foi encontrado."
        )

    with caminho.open("r", encoding="utf-8") as arquivo:
        dados = yaml.safe_load(arquivo)

    if not isinstance(dados, dict):
        raise ValueError(
            "O documento YAML deve possuir um mapa no nível principal."
        )

    return dados


def validar_inventario(dados: dict) -> list[str]:
    """Verifica a presença de campos obrigatórios."""

    erros = []

    campos_obrigatorios = [
        "empresa",
        "ambiente",
        "zos",
        "aplicacoes",
    ]

    for campo in campos_obrigatorios:
        if campo not in dados:
            erros.append(f"Campo obrigatório ausente: {campo}")

    aplicacoes = dados.get("aplicacoes", [])

    if not isinstance(aplicacoes, list):
        erros.append("O campo 'aplicacoes' deve ser uma lista.")
        return erros

    for indice, aplicacao in enumerate(aplicacoes, start=1):
        if not isinstance(aplicacao, dict):
            erros.append(
                f"A aplicação {indice} deve ser representada por um mapa."
            )
            continue

        for campo in ["nome", "codigo", "tipo", "linguagem"]:
            if campo not in aplicacao:
                erros.append(
                    f"Aplicação {indice}: campo '{campo}' ausente."
                )

    return erros


def exibir_relatorio(dados: dict) -> None:
    """Apresenta um resumo legível do inventário."""

    print("=" * 70)
    print("INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME")
    print("=" * 70)

    print(f"Empresa........: {dados['empresa']}")
    print(f"Ambiente.......: {dados['ambiente']}")
    print(f"Sistema z/OS...: {dados['zos']['sistema']}")
    print(f"Sysplex........: {dados['zos']['sysplex']}")
    print(f"LPAR...........: {dados['zos']['lpar']}")
    print()

    aplicacoes = dados["aplicacoes"]

    print(f"Aplicações encontradas: {len(aplicacoes)}")
    print("-" * 70)

    for aplicacao in aplicacoes:
        print(f"Nome...........: {aplicacao['nome']}")
        print(f"Código.........: {aplicacao['codigo']}")
        print(f"Tipo...........: {aplicacao['tipo']}")
        print(f"Linguagem......: {aplicacao['linguagem']}")
        print(f"Programa.......: {aplicacao['programa_principal']}")

        dependencias = aplicacao.get("dependencias", [])
        print(f"Dependências...: {', '.join(dependencias)}")

        opcoes = aplicacao.get("compilacao", {}).get("opcoes", [])
        print(f"Opções COBOL...: {', '.join(opcoes)}")
        print("-" * 70)


def main() -> int:
    try:
        dados = carregar_yaml(ARQUIVO_YAML)

        erros = validar_inventario(dados)

        if erros:
            print("O inventário possui inconsistências:")

            for erro in erros:
                print(f"- {erro}")

            return 8

        exibir_relatorio(dados)
        return 0

    except yaml.YAMLError as erro:
        print(f"Erro de sintaxe YAML: {erro}")
        return 12

    except (FileNotFoundError, ValueError, KeyError) as erro:
        print(f"Erro ao processar inventário: {erro}")
        return 16


if __name__ == "__main__":
    sys.exit(main())

13. Por que usamos `safe_load`?

No código temos:

dados = yaml.safe_load(arquivo)

Essa escolha é muito importante.

Evite usar indiscriminadamente:

yaml.load(arquivo)

Alguns carregadores YAML podem interpretar tags capazes de criar objetos específicos da linguagem ou executar comportamentos indesejados.

Quando o arquivo vem de origem externa ou não confiável, o risco aumenta.

safe_load limita o carregamento a tipos básicos e seguros, como:

mapas;
listas;
strings;
números;
booleanos;
valores nulos.

É o equivalente a aplicar o princípio de menor privilégio:

Não entregue autoridade de sistema a um arquivo de configuração apenas porque sua extensão termina em .yaml.

14. Executando o laboratório

No terminal, com o ambiente virtual ativo:

python ler_inventario.py

O resultado deverá ser semelhante a:

======================================================================
INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME
======================================================================
Empresa........: Bellacosa Galactic Bank
Ambiente.......: homologacao
Sistema z/OS...: ZOS1
Sysplex........: BELLAPLEX
LPAR...........: ZHML01

Aplicações encontradas: 2
----------------------------------------------------------------------
Nome...........: CADASTRO-CLIENTES
Código.........: APL001
Tipo...........: online
Linguagem......: COBOL
Programa.......: PGMCIC01
Dependências...: Db2, CICS, VSAM
Opções COBOL...: RENT, SSRANGE, TEST
----------------------------------------------------------------------
Nome...........: FECHAMENTO-DIARIO
Código.........: APL002
Tipo...........: batch
Linguagem......: COBOL
Programa.......: PGMFEC01
Dependências...: Db2, DFSORT
Opções COBOL...: RENT, OPTFILE
----------------------------------------------------------------------

Parabéns.

Você acabou de:

criar um documento YAML;
representar um ambiente mainframe;
modelar aplicações batch e online;
descrever bibliotecas e dependências;
ler o documento com Python;
validar campos obrigatórios;
transformar dados declarativos em um relatório.

Isso já é a base de muitas automações reais.

15. Provocando um erro de propósito

Todo bom laboratório precisa de um Kobayashi Maru.

Altere:

aplicacoes:
  - nome: CADASTRO-CLIENTES

Para:

aplicacoes:
 - nome: CADASTRO-CLIENTES
     codigo: "APL001"

Execute novamente:

python ler_inventario.py

O parser deverá informar um erro de sintaxe ou estrutura.

Agora teste um erro mais perigoso.

Remova o campo codigo de uma aplicação, mas mantenha a sintaxe válida:

- nome: CADASTRO-CLIENTES
  tipo: online
  linguagem: COBOL

Nesse caso, o parser consegue ler o YAML, porém nossa validação retorna algo semelhante a:

Aplicação 1: campo 'codigo' ausente.

Isso ensina uma diferença essencial:

Validação sintática

Pergunta:

O documento está escrito de maneira compreensível para o parser?

Validação semântica

Pergunta:

O documento contém os dados corretos para nossa aplicação?

Um YAML pode ser sintaticamente perfeito e operacionalmente inútil.

Da mesma forma, um JCL pode passar por determinadas validações e ainda apontar para o dataset errado.

16. YAML Schema: o copybook do YAML

À medida que os documentos crescem, validar tudo manualmente torna-se difícil.

É aí que entram os esquemas.

Um schema pode definir:

quais campos são obrigatórios;
quais tipos são permitidos;
quais valores são aceitos;
qual estrutura deve ser seguida;
quais propriedades são proibidas;
quais listas podem ficar vazias.

Para o mainframer, um schema funciona conceitualmente como uma combinação de:

copybook;
layout de arquivo;
contrato de interface;
regras de validação.

Sem schema:

porta: banana

O YAML é válido, pois banana é uma string.

Mas, se o sistema espera uma porta TCP numérica, o conteúdo está errado.

Com um schema, o editor poderá avisar:

A propriedade porta deve ser um número inteiro.

Esse recurso é especialmente importante em:

pipelines;
Kubernetes;
APIs;
Ansible;
grandes inventários;
configurações corporativas.

17. Anchors e aliases: o COPY do YAML

YAML possui anchors e aliases, que permitem reutilizar blocos.

Exemplo:

configuracao_padrao: &padrao_cobol
  compilador: Enterprise COBOL
  opcoes:
    - RENT
    - SSRANGE
    - TEST

aplicacoes:
  - nome: CLIENTES
    compilacao: *padrao_cobol

  - nome: CONTAS
    compilacao: *padrao_cobol

O símbolo:

&padrao_cobol

cria uma âncora.

O símbolo:

*padrao_cobol

faz referência a ela.

É tentador pensar nisso como um COPY do COBOL.

Entretanto, tenha cuidado.

Anchors podem reduzir repetição, mas também tornar o documento mais difícil de entender. Algumas ferramentas possuem suporte parcial ou adotam comportamentos específicos.

Use anchors quando:

houver repetição significativa;
a equipe conhecer o recurso;
a ferramenta suportá-lo corretamente;
o ganho de manutenção superar a perda de clareza.

Não transforme seu YAML em um labirinto Klingon.

18. Boas práticas para mainframers

Use dois espaços por nível

aplicacao:
  nome: CLIENTES

A consistência vale mais que a preferência individual.

Nunca use TAB

Configure o editor para substituir TAB por espaços.

Prefira nomes claros

Evite:

apl:
  nm: CLI
  tp: O

Prefira:

aplicacao:
  nome: CLIENTES
  tipo: online

Use uma convenção de nomes

Escolha um padrão:

programa_principal

ou:

programa-principal

Evite misturar:

programa_principal:
programa-principal:
ProgramaPrincipal:

Coloque códigos entre aspas

codigo: "000123"

Coloque horários entre aspas

inicio: "08:00"

Coloque datas entre aspas quando desejar tratá-las como texto

data: "2026-07-18"

Não grave segredos

Nunca faça:

usuario: ADMIN
senha: SENHA123

Valide antes do commit

O fluxo ideal é:

editar → validar → revisar → testar → commit → pipeline

Mantenha arquivos pequenos

Um YAML com milhares de linhas torna-se difícil de revisar.

Considere separar por:

ambiente;
aplicação;
domínio;
equipe;
finalidade.

Documente a intenção

# Ativada somente em homologação para testes de integração
simular_falha_db2: true

O comentário explica o motivo, não apenas repete o nome do campo.

Use controle de versão

Arquivos YAML devem ser armazenados no Git sempre que fizer sentido.

Assim você consegue saber:

quem mudou;
o que mudou;
quando mudou;
por que mudou;
qual versão estava funcionando.

19. Cuidados que evitam desastres

Um espaço pode mudar a hierarquia

Revise sempre o diff antes do commit.

Valores podem ser interpretados automaticamente

Quando o tipo for importante, use aspas ou schemas.

YAML válido não significa configuração válida

Teste com a ferramenta que realmente consumirá o arquivo.

Ambientes não devem compartilhar segredos

Produção, homologação e desenvolvimento precisam de separação adequada.

Copiar da internet exige revisão

Um exemplo encontrado em um fórum pode:

usar outra versão;
depender de outra ferramenta;
conter parâmetros obsoletos;
assumir permissões inexistentes;
expor credenciais;
executar ações destrutivas.

IA também pode errar a indentação

Um YAML gerado por inteligência artificial deve passar por:

revisão humana;
lint;
schema;
teste em ambiente controlado;
análise de segurança.

Nunca envie um arquivo gerado automaticamente direto para produção.

Cuidado com comandos multilinha

Um comando embutido em YAML pode parecer correto, mas ser interpretado de forma diferente pelo shell.

Cuidado com duplicidade de chaves

Observe:

ambiente: teste
ambiente: producao

Dependendo da biblioteca, o segundo valor pode sobrescrever o primeiro sem o aviso esperado.

Para uma mudança de produção, isso pode ser desastroso.

Use validadores capazes de detectar chaves duplicadas.

20. Como evoluir depois deste laboratório

Depois de dominar este exemplo, o Programador COBOL Padawan pode avançar por uma trilha segura.

Nível 1 — Leitura

Aprenda a identificar:

mapas;
listas;
strings;
números;
booleanos;
valores nulos;
comentários;
hierarquia.

Nível 2 — Validação

Use:

extensão YAML no editor;
schemas;
linters;
scripts Python;
testes automatizados.

Nível 3 — Automação local

Crie scripts que leiam YAML para:

gerar JCL;
produzir relatórios;
montar parâmetros;
validar inventários;
criar documentação;
comparar ambientes.

Nível 4 — Git

Armazene arquivos em repositórios e pratique:

branch;
commit;
pull request;
diff;
revisão de código.

Nível 5 — CI/CD

Use YAML para criar pipelines de:

compilação;
testes;
análise estática;
empacotamento;
deploy;
rollback.

Nível 6 — Ansible para z/OS

Aprenda playbooks que possam:

criar datasets;
copiar arquivos;
submeter jobs;
consultar resultados;
executar comandos;
automatizar tarefas administrativas.

Nível 7 — Infraestrutura declarativa

Explore ferramentas que transformam YAML em estado operacional.

Aqui ocorre uma mudança importante de mentalidade.

Em vez de dizer apenas:

Execute este comando.

Você passa a declarar:

Quero que o ambiente permaneça neste estado.

21. Comparando YAML, JCL, JSON e XML

YAML

Excelente para arquivos legíveis e configurações hierárquicas.

programa:
  nome: PGMCAD01
  tipo: batch

JSON

Muito usado em APIs e comunicação entre aplicações.

{
  "programa": {
    "nome": "PGMCAD01",
    "tipo": "batch"
  }
}

A estrutura de dados é semelhante, mas JSON exige mais sinais de pontuação.

XML

Possui tags de abertura e fechamento.

<programa>
  <nome>PGMCAD01</nome>
  <tipo>batch</tipo>
</programa>

É mais verboso, porém muito utilizado em integrações corporativas e sistemas legados.

JCL

Descreve a execução de trabalhos no z/OS:

//STEP01 EXEC PGM=PGMCAD01
//STEPLIB DD DSN=USER01.LOAD,DISP=SHR

YAML não substitui automaticamente o JCL.

Uma automação poderá ler YAML e gerar ou submeter JCL, mas o JES continuará precisando compreender o trabalho no formato adequado.

A ponte pode ser:

YAML
  ↓
Pipeline ou script
  ↓
JCL
  ↓
JES2
  ↓
Programa COBOL

22. Curiosidades para a tripulação

YAML nasceu para ser legível

Seu desenho privilegia estruturas que humanos possam editar com relativa facilidade.

JSON pode ser visto como um subconjunto estrutural do YAML 1.2

A compatibilidade com o modelo de dados do JSON foi um dos objetivos importantes da linha YAML 1.2.

A extensão preferida é `.yaml`

Também é comum encontrar:

.yml

Porém, .yaml é mais explícita.

YAML não é automaticamente simples

Documentos pequenos são agradáveis.

Documentos gigantes, com anchors, merges, múltiplos documentos e regras implícitas, podem tornar-se difíceis de manter.

Indentação é estrutura, não decoração

No COBOL, uma indentação visual ruim pode dificultar a leitura.

No YAML, uma indentação errada pode mudar o significado.

A melhor configuração é aquela que pode ser validada

Quanto mais crítica for a automação, menos você deve depender apenas da leitura humana.

23. Easter egg: o arquivo de missão da Enterprise

Crie:

missao-enterprise.yaml

---
nave:
  nome: USS Enterprise
  registro: NCC-1701
  capitao: James T. Kirk

tripulacao:
  - nome: Spock
    funcao: ciencia
    linguagem_preferida: YAML

  - nome: Montgomery Scott
    funcao: engenharia
    linguagem_preferida: JCL

  - nome: Nyota Uhura
    funcao: comunicacoes
    linguagem_preferida: JSON

missao:
  destino: Sistema IBM Z
  objetivo: modernizar_sem_destruir
  diretriz_principal: |
    Integrar o novo ao legado.
    Preservar aquilo que funciona.
    Automatizar aquilo que se repete.
    Documentar aquilo que ninguém mais compreende.

alertas:
  tab_encontrado: vermelho
  segredo_no_repositorio: vermelho
  deploy_sem_teste: vermelho
  yaml_validado: verde

mensagem_final: >
  Vida longa ao COBOL,
  prosperidade ao mainframe
  e atenção absoluta à indentação.
...

Observe o detalhe:

objetivo: modernizar_sem_destruir

Essa talvez seja a missão mais importante de toda modernização mainframe.

Modernizar não significa jogar fora décadas de regras de negócio.

Significa:

entender;
proteger;
documentar;
integrar;
automatizar;
evoluir.

24. Conclusão: o YAML como nova ponte do mainframe

YAML não substituirá o COBOL.

Não substituirá o JCL.

Não substituirá o CICS, o Db2, o IMS ou o z/OS.

Sua função é diferente.

YAML permite descrever configurações e intenções de uma forma que ferramentas modernas conseguem interpretar.

Para o mainframer, ele representa uma nova camada de comunicação entre:

o código COBOL;
os pipelines;
os repositórios Git;
os processos de build;
as ferramentas de automação;
os ambientes distribuídos;
a infraestrutura;
as equipes modernas de desenvolvimento.

O veterano que conhece COBOL possui uma vantagem enorme.

Ele já entende:

estruturas hierárquicas;
contratos de dados;
processamento previsível;
validação;
disciplina operacional;
ambientes controlados;
importância da compatibilidade;
consequências de um erro em produção.

Aprender YAML não é começar do zero.

É traduzir conhecimentos antigos para uma nova interface.

O programador que entende um copybook consegue compreender um schema.

Quem entende um SYSIN consegue compreender um arquivo declarativo.

Quem entende JCL consegue compreender pipelines.

Quem conhece PROC e parâmetros consegue compreender templates.

Quem respeita produção aprende rapidamente a respeitar indentação.

A verdadeira transformação não ocorre quando o mainframer abandona sua experiência.

Ela ocorre quando usa essa experiência para dominar novas ferramentas.

Portanto, abra o editor, crie seus primeiros arquivos, provoque erros em ambiente controlado, valide cada estrutura e coloque o YAML para trabalhar ao lado do COBOL.

Porque, no fim das contas, seja dentro de uma LPAR, de um container ou da USS Enterprise, uma regra continua universal:

Configuração sem validação é apenas um futuro incidente esperando sua janela de produção.

Vida longa ao COBOL.

Prosperidade ao IBM Z.

E que nenhum TAB clandestino atravesse os escudos da sua indentação.

Translate

sexta-feira, 27 de dezembro de 2024

YAML na Prática : O guia do Programador COBOL Padawan para dominar configurações, automação e infraestrutura sem provocar um ABEND na indentação