# YAML anchor > YAML anchor é um recurso da linguagem YAML que permite dar um nome a um bloco de configuração, usando o símbolo &, e reaproveitá-lo em outros pontos do mesmo arquivo por meio de uma referência, chamada alias, com o símbolo *. Serve para evitar repetição em arquivos de configuração, como pipelines, manifestos de infraestrutura e especificações de API. **Também conhecido como:** Âncora YAML, Âncora em YAML, Anchor e alias no YAML, YAML anchors and aliases, YAML anchor **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### YAML anchor funciona em JSON? Não. JSON não tem esse recurso. Quando um YAML com anchors é convertido para JSON, o conteúdo referenciado é copiado por extenso em cada ponto onde havia um alias. ### Posso usar um anchor definido em outro arquivo? Não. Anchors e aliases só funcionam dentro do mesmo arquivo YAML. Para reaproveitar conteúdo entre arquivos, é preciso usar recursos da ferramenta, como includes, templates ou $ref em especificações OpenAPI. ### Alterar um campo depois do merge muda o bloco original? Não. Ao usar <<: *nome e redefinir um campo, a alteração vale apenas para aquele bloco. O bloco ancorado e os demais que o referenciam continuam com os valores originais. ### Preciso de YAML anchor para integrar com uma API fiscal? Não. É apenas uma conveniência para organizar arquivos de configuração do seu próprio sistema. A comunicação com a API fiscal normalmente usa JSON nas requisições, independentemente de como sua configuração interna é escrita. ## Termos relacionados - [OpenAPI](https://conota.dev/glossario/openapi.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Ambiente de produção](https://conota.dev/glossario/ambiente-de-producao.md) --- Fonte: [YAML anchor](https://conota.dev/glossario/yaml-anchor/) · Atualizado em 2026-10-22