YAML tag

O que é uma YAML tag?

YAML é um formato de texto usado para escrever configurações e descrever dados de forma legível, com recuo de espaços em vez de chaves e colchetes. Por padrão, o leitor de YAML tenta adivinhar o tipo de cada valor: se parece número, vira número; se parece verdadeiro ou falso, vira booleano.

A tag é a forma de dizer explicitamente qual é o tipo, sem deixar para a adivinhação. Ela aparece antes do valor e começa com ponto de exclamação, como em !!str (texto), !!int (número inteiro), !!float (número decimal), !!bool (verdadeiro ou falso) ou !!binary (dado binário codificado em Base64).

Para que serve a YAML tag em integrações fiscais?

Muitos dados fiscais parecem números, mas precisam ser tratados como texto. CNPJ, CEP, código de município e alguns códigos tributários podem começar com zero. Se o leitor de YAML transformar esses valores em número, os zeros à esquerda desaparecem e o dado fica inválido.

Ao marcar o valor com !!str, a pessoa garante que ele será lido exatamente como foi escrito. Isso evita erros de validação quando a configuração é usada para montar uma requisição a uma API de emissão de NF-e, NFS-e ou CT-e.

Como funciona a sintaxe das tags?

Existem três formas principais. As tags com dois pontos de exclamação, como !!str, são atalhos para os tipos padrão da especificação YAML. As tags locais, com um só ponto de exclamação, como !Ambiente, são definidas pela própria aplicação e têm o significado que o programa leitor atribuir a elas. Há ainda a tag não específica, apenas !, que força um valor simples a ser lido como texto.

Por exemplo, a linha cnpj: !!str 01234567000189 mantém o zero inicial. Sem a tag, o mesmo valor poderia ser convertido para o número 1234567000189.

Qual a diferença entre usar tag e usar aspas?

Colocar o valor entre aspas também faz o YAML tratá-lo como texto, e na prática é a solução mais comum para casos simples, como cnpj: "01234567000189". O resultado é equivalente ao uso de !!str.

A tag vai além das aspas porque pode indicar outros tipos, como binário, data ou tipos personalizados da aplicação. Ela também deixa a intenção mais explícita para quem lê o arquivo, o que ajuda em configurações compartilhadas por equipes.

Quais cuidados de segurança envolvem as YAML tags?

Algumas bibliotecas de leitura de YAML, quando usadas no modo completo, aceitam tags personalizadas que criam objetos do próprio programa. Um arquivo malicioso pode explorar isso para executar código indevido no servidor.

Por isso, ao ler arquivos de origem externa, recomenda-se usar o modo de leitura seguro da biblioteca, que aceita apenas os tipos padrão. Também é boa prática não guardar certificados digitais ou senhas diretamente em arquivos YAML versionados, preferindo uma ferramenta de gerenciamento de segredos.

Exemplos de YAML tag

• Em um arquivo de configuração de um ERP, o desenvolvedor escreve codigo_municipio: !!str 0012345 para impedir que o zero à esquerda seja removido antes do envio da NFS-e.
• Uma equipe usa ambiente: !!str homologacao em um arquivo YAML para definir em qual ambiente da API fiscal os documentos de teste serão emitidos.
• Em uma especificação OpenAPI escrita em YAML, um campo de exemplo de CEP é marcado como texto para que a documentação não exiba o valor como número.
• Um script de testes lê um certificado de teste representado com a tag !!binary, que indica um conteúdo em Base64 a ser convertido em bytes.