YAML sequence

O que é uma YAML sequence?

YAML é um formato de texto criado para ser fácil de ler por pessoas. Ele organiza informações em três peças básicas: valores simples, como um número ou um texto; mapeamentos, que são pares de chave e valor; e sequências, que são listas.

A sequence, ou sequência, é justamente a lista. Ela guarda vários itens em uma ordem definida, como os tipos de documento fiscal que um sistema emite, os ambientes disponíveis em uma API ou os campos obrigatórios de um payload. A ordem dos itens é preservada, e o mesmo valor pode aparecer mais de uma vez.

Como se escreve uma sequence em YAML?

A forma mais comum é o estilo em bloco: cada item fica em uma linha, começando com um hífen seguido de um espaço. Por exemplo, uma chave chamada documentos pode ter, nas linhas de baixo e com o mesmo recuo, os itens – nfe, – nfce e – nfse.

Também existe o estilo em linha, chamado flow style, parecido com JSON: os itens ficam entre colchetes e separados por vírgulas, como documentos: [nfe, nfce, nfse]. Os dois estilos produzem o mesmo resultado quando o arquivo é lido por um programa.

Os itens de uma sequence podem ser valores simples, outros mapeamentos ou até outras listas. É comum ver uma lista de objetos, em que cada hífen abre um bloco com várias chaves, como uma lista de empresas emissoras em que cada item tem CNPJ, razão social e regime tributário.

Qual a diferença entre sequence e mapping em YAML?

A sequence é uma lista de itens identificados apenas pela posição: primeiro, segundo, terceiro. Já o mapping é um conjunto de pares chave e valor, em que cada informação tem um nome, como cnpj: valor ou ambiente: homologacao.

Na prática, os dois aparecem juntos. Um mapping descreve um objeto, e uma sequence agrupa vários desses objetos. Visualmente, a diferença está no hífen: linhas que começam com hífen são itens de uma lista; linhas no formato chave seguida de dois-pontos são partes de um mapping.

Qual a relação entre YAML sequence e array em JSON?

Uma YAML sequence corresponde diretamente a um array em JSON. Uma lista escrita em YAML com hífens pode ser convertida para JSON entre colchetes sem perda de informação, e o caminho inverso também funciona.

Por isso, muitas ferramentas aceitam os dois formatos para o mesmo conteúdo. Uma especificação OpenAPI, por exemplo, pode ser escrita em YAML ou em JSON. Já os payloads enviados a APIs fiscais costumam usar JSON, enquanto o YAML aparece mais em documentação e configuração.

Onde YAML sequences aparecem em integrações fiscais?

Em especificações OpenAPI, sequences listam os servidores da API, como homologação e produção, os parâmetros de um endpoint, os campos obrigatórios de um schema e os valores permitidos em um enum, como os possíveis status de um documento fiscal.

Na infraestrutura, manifestos Kubernetes usam sequences para listar contêineres, variáveis de ambiente e portas. Arquivos de pipelines de deploy também usam listas para descrever as etapas de build, testes e publicação de um backend de integração fiscal.

Quais erros são comuns ao usar sequences em YAML?

O erro mais frequente é de recuo. Em YAML, a indentação define a estrutura, então um item com espaços a mais ou a menos pode sair da lista ou virar outra coisa. Tabulações não são permitidas para indentar; use apenas espaços. Esquecer o espaço depois do hífen também quebra a leitura.

Outro cuidado envolve códigos fiscais com zeros à esquerda, como CST 00 ou códigos de NCM e de município. Sem aspas, alguns leitores de YAML podem interpretá-los como números e descartar os zeros. Colocar esses valores entre aspas garante que sejam tratados como texto.

Exemplos de YAML sequence

• Em uma especificação OpenAPI escrita em YAML, a chave servers contém uma sequence com dois itens: a URL do ambiente de homologação e a URL do ambiente de produção.
• No schema de emissão de NF-e, a chave required traz uma sequence com os nomes dos campos obrigatórios, como emitente, destinatario e itens.
• Um arquivo de configuração de um ERP define a sequence tipos_documento: [nfe, nfce, nfse] para indicar quais documentos cada filial pode emitir.
• Um manifesto Kubernetes do serviço de integração fiscal usa uma sequence em env para listar variáveis de ambiente, como o endereço da API e a referência ao segredo que guarda a API Key.