YAML block style

Como funciona o YAML block style?

YAML é um formato de texto usado para representar dados estruturados, como configurações, listas e especificações de APIs. No estilo de bloco, a hierarquia dos dados é indicada pela posição do texto: o que está mais à direita, com mais espaços no começo da linha, pertence ao item logo acima.

Na prática, cada informação fica em sua própria linha. Uma chave como empresa pode ter, abaixo dela e com dois espaços de recuo, as linhas cnpj, razao_social e ambiente. Quem lê entende o agrupamento só de olhar, sem precisar procurar onde abre ou fecha uma chave.

Quais são os elementos do estilo de bloco?

São três estruturas principais. O mapeamento de bloco reúne pares no formato chave: valor, um por linha. A sequência de bloco é uma lista em que cada item começa com hífen e espaço, como uma lista de CNPJs ou de tipos de documento (NF-e, NFS-e, NFC-e).

O terceiro elemento são os escalares de bloco, usados para textos de várias linhas. O indicador | (literal) preserva as quebras de linha exatamente como foram escritas. O indicador > (dobrado) junta as linhas em um único parágrafo, trocando as quebras por espaços. Variações como |- e >- removem a quebra de linha final do texto.

Qual a diferença entre block style e flow style?

O flow style (estilo de fluxo) é a outra forma de escrever YAML. Ele usa chaves para mapeamentos e colchetes para listas, tudo em uma linha, de modo muito parecido com JSON. Por exemplo, uma lista de documentos pode ser escrita como [nfe, nfse, cte].

Os dois estilos representam os mesmos dados e podem até ser misturados no mesmo arquivo. O estilo de bloco é preferido em arquivos editados por pessoas, porque facilita a leitura e a revisão de mudanças. O estilo de fluxo costuma aparecer em trechos curtos ou quando os dados vêm de outro sistema.

Onde o YAML block style aparece em integrações fiscais?

Muitas especificações de APIs REST, inclusive as de emissão fiscal, são escritas em YAML no estilo de bloco, descrevendo endpoints, parâmetros e respostas. Desenvolvedores também usam YAML para configurar a própria integração: ambiente de homologação ou produção, endereço da API, tempo limite das requisições e regras de retentativa.

Vale notar que o YAML geralmente fica do lado do sistema do cliente ou da documentação. A comunicação com a API em si costuma usar JSON, e os documentos fiscais autorizados são arquivos XML. O YAML entra como forma organizada de guardar configurações e descrições.

Quais cuidados evitam erros ao usar o estilo de bloco?

A indentação deve usar apenas espaços, nunca tabulação, e precisa ser consistente. Um espaço a mais ou a menos muda o significado do arquivo ou causa erro de leitura.

Valores que parecem números mas são códigos devem ficar entre aspas. Um CNPJ, CEP ou código NCM com zeros à esquerda, se escrito sem aspas, pode ser interpretado como número e perder esses zeros. O mesmo vale para textos com dois-pontos ou caracteres especiais.

Por fim, senhas de certificado digital, API Keys e outros segredos não devem ficar gravados em arquivos YAML versionados. O ideal é referenciar variáveis de ambiente ou um cofre de segredos.

Exemplos de YAML block style

• Um ERP guarda sua configuração de integração fiscal em um arquivo YAML no estilo de bloco, com uma chave fiscal e, abaixo dela, as linhas ambiente: homologacao e timeout_segundos: 30, cada uma recuada com dois espaços.
• Uma equipe de desenvolvimento lista as empresas emissoras em uma sequência de bloco: cada linha começa com hífen e traz o CNPJ entre aspas, para evitar que zeros à esquerda sejam perdidos.
• A documentação de uma API REST de emissão fiscal é escrita em YAML no estilo de bloco, descrevendo o endpoint de emissão de NFS-e, os campos obrigatórios e os códigos de resposta.
• Um texto padrão de informações complementares da nota é armazenado em um escalar literal (|), mantendo as quebras de linha exatamente como o setor fiscal redigiu.