YAML anchor

O que é YAML e onde aparece o anchor?

YAML é um formato de texto usado para escrever configurações de forma legível para pessoas. Ele organiza informações em pares de chave e valor, com a hierarquia definida pela indentação. É comum em arquivos de pipelines de deploy, manifestos de Kubernetes, arquivos do Docker Compose e especificações OpenAPI.

O anchor, ou âncora, é uma marcação dentro desse arquivo. Ela funciona como um apelido: você define um trecho uma única vez e depois aponta para ele sempre que precisar do mesmo conteúdo, sem copiar e colar.

Como funciona um YAML anchor na prática?

São três peças. A âncora é criada com & seguido de um nome, como &padrao_api. O alias, escrito como *padrao_api, insere naquele ponto exatamente o conteúdo marcado. E a chave de mesclagem, escrita como <<: *padrao_api, copia os campos de um bloco para dentro de outro, permitindo acrescentar ou sobrescrever alguns deles.

Por exemplo: um bloco chamado &base pode conter timeout: 30 e retries: 3. Em seguida, os blocos homologacao e producao usam <<: *base e cada um define apenas sua própria url. Quem lê o arquivo depois de processado vê os dois ambientes completos, cada um com timeout, retries e url.

Para que serve o YAML anchor em uma integração fiscal?

Sistemas que emitem documentos fiscais por API costumam ter configurações muito parecidas entre ambientes e serviços: tempo limite de requisição, número de tentativas, cabeçalhos, limites de recursos e variáveis de ambiente. Com anchors, esses valores comuns ficam definidos em um só lugar.

Isso reduz erros de digitação e evita que um ambiente fique desatualizado em relação ao outro. Se a equipe decidir aumentar o tempo limite das chamadas de emissão, basta alterar o bloco ancorado, e todos os pontos que o referenciam passam a usar o novo valor.

Quais são as limitações do YAML anchor?

A âncora só vale dentro do mesmo arquivo, e precisa ser definida antes do alias que a utiliza. Não é possível referenciar um bloco que está em outro arquivo usando apenas anchors.

A chave de mesclagem (<<) vem de uma versão mais antiga da especificação YAML e não faz parte da versão 1.2 oficial, embora muitas ferramentas a aceitem. Por isso, vale testar se a ferramenta usada no projeto interpreta o recurso corretamente. Também é importante lembrar que o uso exagerado de anchors pode deixar o arquivo difícil de entender para quem não conhece o recurso.

Qual a diferença entre YAML anchor e $ref no OpenAPI?

O anchor é um recurso da própria linguagem YAML e é resolvido no momento em que o arquivo é lido: o conteúdo é simplesmente duplicado na estrutura final. Ele não existe em JSON, então some quando o arquivo é convertido.

Já o $ref é um mecanismo do OpenAPI e do JSON Schema para apontar para componentes reutilizáveis, inclusive em outros arquivos. Em especificações de API, como a documentação dos endpoints de emissão de NF-e ou NFS-e, o $ref costuma ser a forma recomendada de reaproveitar esquemas, porque é entendido por ferramentas como geradores de código e o Swagger UI.

Exemplos de YAML anchor

• Um arquivo de pipeline de deploy define um bloco &deploy_padrao com as etapas comuns e o reutiliza nos jobs de homologação e de produção do serviço que envia notas fiscais para a API.
• Um arquivo Docker Compose usa <<: *env_comum para compartilhar variáveis de ambiente entre o worker que processa a fila de emissão e o serviço que recebe webhooks de status.
• Um manifesto de configuração de um ERP define &retry_politica com número de tentativas e intervalo entre elas, aplicando a mesma política às chamadas de NF-e, NFC-e e CT-e.
• Um time centraliza em um bloco ancorado os limites de CPU e memória dos containers da integração fiscal, evitando valores diferentes entre réplicas.