YAML block scalar

O que é um block scalar em YAML?

YAML é um formato de texto usado para arquivos de configuração e para descrever APIs. Nele, um escalar é um valor simples, como um número ou um texto. O block scalar, ou escalar de bloco, é um jeito específico de escrever textos que ocupam mais de uma linha.

Em vez de colocar tudo entre aspas e usar códigos como n para indicar quebra de linha, você escreve a chave, coloca um símbolo especial (| ou >) e, nas linhas de baixo, digita o texto com recuo. O YAML entende que tudo o que está recuado faz parte daquele valor.

Qual a diferença entre o estilo literal (|) e o dobrado (>)?

O estilo literal, indicado pela barra vertical |, preserva cada quebra de linha exatamente como foi escrita. É o mais indicado quando a formatação importa, como em um certificado em formato PEM, um trecho de XML ou um script.

O estilo dobrado, indicado pelo sinal >, junta as linhas em um único parágrafo, trocando as quebras por espaços. Linhas em branco continuam separando parágrafos. Ele serve para textos longos de leitura, como descrições, que ficam mais organizados no arquivo sem virar uma linha gigante.

O que são os indicadores de chomping?

Chomping é a regra que define o que acontece com as quebras de linha no final do bloco. Sem indicador, o YAML mantém apenas uma quebra final. Com o sinal de menos (|- ou >-), todas as quebras finais são removidas. Com o sinal de mais (|+ ou >+), todas são mantidas.

Esse detalhe parece pequeno, mas pode mudar o resultado. Um valor que será comparado, assinado ou enviado a um sistema externo pode falhar por causa de uma quebra de linha a mais no fim do texto.

Onde o block scalar aparece na integração fiscal?

Equipes que integram sistemas a uma API fiscal costumam usar YAML em arquivos de configuração, pipelines de implantação e especificações de API. Nesses arquivos, o block scalar aparece para guardar textos longos: descrições de endpoints, exemplos de requisição, mensagens de erro e modelos de informações complementares de uma nota.

Também é comum em configurações de ambientes que armazenam certificados ou chaves em formato de texto. Nesses casos, o estilo literal é o correto, porque a estrutura de linhas precisa ser preservada. Dados sensíveis, porém, devem ficar em um cofre de segredos, e não escritos diretamente em arquivos versionados.

Quais erros são mais comuns ao usar block scalars?

O erro mais frequente é o recuo inconsistente. Todas as linhas do bloco precisam ter pelo menos o mesmo recuo da primeira linha; se uma linha voltar para trás, o YAML entende que o bloco terminou. Misturar tabulação com espaços também causa falhas, porque o YAML não aceita tabulação para recuo.

Outro engano é usar > quando o conteúdo precisa manter as quebras, o que corrompe um certificado ou um XML. Vale lembrar ainda que, dentro do bloco, o símbolo # não inicia comentário: ele vira parte do texto.

Exemplos de YAML block scalar

• Em um arquivo de configuração de homologação, a chave certificado_pem usa o estilo literal (|) para que as linhas BEGIN CERTIFICATE e END CERTIFICATE e o conteúdo intermediário sejam lidos exatamente como no arquivo original.
• Em uma especificação OpenAPI da API de emissão de NFS-e, o campo description do endpoint usa o estilo dobrado (>) para escrever uma explicação de vários parágrafos sem criar linhas muito longas no arquivo.
• Um time de ERP guarda em YAML o modelo do texto de informações complementares da NF-e usando |- para manter as quebras de linha internas, mas sem a quebra extra no final que poderia aparecer no DANFE.
• Em um pipeline de implantação, um passo que executa vários comandos de teste contra o ambiente de homologação fiscal usa o estilo literal para listar cada comando em uma linha separada.