# Glossário de A a Z — letra Y > 19 termos. Glossário compacto: https://conota.dev/glossario/llms-full.txt --- # YAML alias > YAML alias é um recurso da linguagem YAML que permite reaproveitar um bloco de dados já definido em outro ponto do mesmo arquivo. O bloco original recebe uma âncora, marcada com &, e o alias, marcado com *, aponta para ela, evitando repetição em arquivos de configuração e especificações de API. **Também conhecido como:** Alias YAML, Referência YAML, Âncora e alias YAML, YAML anchor e alias, YAML alias **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML e onde entra o alias? YAML é um formato de texto usado para escrever dados estruturados de forma legível para pessoas. Ele é muito comum em arquivos de configuração, manifestos de infraestrutura e especificações de API, como documentos OpenAPI que descrevem os endpoints de uma API fiscal. O alias é a forma que o YAML oferece para dizer "use aqui o mesmo conteúdo que já escrevi lá em cima". Em vez de copiar e colar um trecho várias vezes, você escreve uma vez, dá um nome a ele e depois faz referência a esse nome quantas vezes precisar. ## Como funciona a âncora e o alias no YAML? O funcionamento envolve dois símbolos. O & cria uma âncora: ao escrever, por exemplo, configuracao_padrao: &padrao, você marca aquele bloco com o nome padrao. Depois, em qualquer ponto posterior do arquivo, escrever *padrao faz o leitor do YAML tratar aquele lugar como se o bloco inteiro estivesse ali. Uma regra importante é a ordem: o alias só pode apontar para uma âncora que já apareceu antes no arquivo. Além disso, âncoras e aliases valem apenas dentro do mesmo documento YAML; não é possível referenciar um bloco que está em outro arquivo usando esse recurso. ## Para que serve o YAML alias na prática? A principal utilidade é eliminar repetição. Em arquivos longos, é comum que vários trechos compartilhem as mesmas informações, como tempo limite de conexão, número de tentativas ou cabeçalhos de autenticação. Com alias, essas informações ficam em um único lugar. Isso reduz erros de manutenção: se um valor mudar, basta alterá-lo na âncora, e todos os pontos que usam o alias passam a refletir a mudança. Em integrações fiscais, isso ajuda a manter consistentes, por exemplo, as configurações dos ambientes de homologação e de produção. ## O que é a chave de mesclagem << usada junto com alias? Muitos leitores de YAML aceitam a chave especial <<, chamada de merge key. Ao escrever <<: *padrao dentro de um bloco, você copia todos os campos da âncora para aquele bloco e pode, em seguida, sobrescrever apenas os campos que precisam ser diferentes. Esse recurso é útil para criar variações de uma configuração base. Porém, ele não faz parte da especificação mais recente do YAML em todos os contextos, então o suporte depende da biblioteca ou ferramenta usada. Vale testar antes de confiar nele em arquivos críticos. ## Qual a diferença entre YAML alias e JSON? O JSON não possui um mecanismo equivalente a âncoras e aliases: cada dado precisa ser escrito por completo onde for usado. Quando um arquivo YAML com aliases é convertido para JSON, os aliases são expandidos, ou seja, o conteúdo referenciado é copiado para cada ponto em que aparecia. Por isso, um arquivo YAML pode ser bem mais curto que o JSON equivalente. Para a API que recebe os dados, o resultado é o mesmo; o alias é apenas uma facilidade de escrita para quem mantém o arquivo. ## Quais cuidados tomar ao usar YAML alias? O uso excessivo de aliases pode deixar o arquivo difícil de entender, porque quem lê precisa voltar até a âncora para saber o que está sendo reaproveitado. Nomes de âncora claros ajudam bastante. Há também um cuidado de segurança: aliases aninhados podem ser usados para criar arquivos pequenos que se expandem em volumes enormes de dados ao serem lidos, sobrecarregando o sistema. Sistemas que processam YAML enviado por terceiros devem usar bibliotecas com limites de expansão ou desativar esse recurso. ## Exemplos de YAML alias - Em uma especificação OpenAPI escrita em YAML, a equipe define uma única vez a resposta de erro de validação fiscal com a âncora &erro_validacao e reaproveita com *erro_validacao nos endpoints de emissão de NF-e, NFS-e e NFC-e. - Um arquivo de configuração de um ERP define um bloco &retry_padrao com número de tentativas e intervalo entre elas e o reutiliza nas chamadas de emissão, consulta de status e cancelamento de documentos fiscais. - Um manifesto de Kubernetes usa uma âncora para os limites de memória e CPU e aplica o mesmo bloco, via alias, aos serviços que consomem a API fiscal e aos que processam webhooks. - Um time cria uma configuração base de ambiente com &base e, usando <<: *base, monta as variantes de homologação e de produção alterando apenas a URL do endpoint e a chave de API. ## Perguntas frequentes ### Alias e âncora são a mesma coisa? Não. A âncora, marcada com &, nomeia o bloco original. O alias, marcado com *, é a referência que reaproveita esse bloco em outro ponto. Um funciona em conjunto com o outro. ### Posso usar alias para referenciar outro arquivo YAML? Não. Âncoras e aliases funcionam apenas dentro do mesmo documento YAML. Para reaproveitar conteúdo entre arquivos, é preciso usar recursos da ferramenta específica, como referências do OpenAPI. ### Se eu alterar o valor no alias, a âncora muda também? Não é possível alterar o conteúdo pelo alias diretamente. Para mudar só alguns campos em um ponto específico, usa-se a chave de mesclagem << e sobrescrevem-se os campos desejados, quando a ferramenta oferece suporte. ### A API fiscal entende YAML com aliases? Normalmente APIs fiscais recebem JSON. O YAML com aliases costuma ser usado em configurações e documentação; se for convertido para JSON antes do envio, os aliases são expandidos e a API recebe os dados completos. ## Termos relacionados - [OpenAPI](https://conota.dev/glossario/openapi.md) - [JSON](https://conota.dev/glossario/json.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) - [Swagger UI](https://conota.dev/glossario/swagger-ui.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) --- Fonte: [YAML alias](https://conota.dev/glossario/yaml-alias/) · Atualizado em 2026-10-22 --- # 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 --- # YAML block scalar > YAML block scalar é a forma de escrever textos de várias linhas em arquivos YAML usando os indicadores | (literal) ou > (dobrado). Em vez de aspas e caracteres de escape, o conteúdo fica recuado abaixo da chave. Isso facilita registrar certificados em texto, chaves, mensagens longas e descrições em arquivos de configuração e documentação de APIs. **Também conhecido como:** Escalar de bloco YAML, String multilinha em YAML, Bloco literal YAML, Bloco dobrado YAML, YAML block scalar **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### Preciso usar aspas dentro de um block scalar? Não. Dentro do bloco, o texto é lido como está, sem necessidade de aspas ou caracteres de escape. Aspas, dois-pontos e barras invertidas fazem parte do conteúdo normalmente. ### Quando usar | e quando usar >? Use | quando as quebras de linha precisam ser preservadas, como em certificados, XML ou scripts. Use > para textos corridos, como descrições, em que as linhas podem ser unidas em parágrafos. ### O JSON tem algo equivalente ao block scalar? Não. Em JSON, textos de várias linhas precisam ficar entre aspas, com quebras representadas por n. Por isso, ao converter YAML para JSON, o conteúdo do bloco vira uma string comum com escapes. ### Posso guardar a senha do certificado A1 em um block scalar? Tecnicamente sim, mas não é recomendado deixar senhas ou chaves em arquivos versionados. O ideal é usar um gerenciador de segredos e apenas referenciar o valor na configuração. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) --- Fonte: [YAML block scalar](https://conota.dev/glossario/yaml-block-scalar/) · Atualizado em 2026-10-22 --- # YAML block style > YAML block style é a forma de escrever dados no formato YAML usando quebras de linha e indentação, em vez de chaves e colchetes, para mostrar a estrutura. Listas aparecem com hífens, pares chave-valor ficam um por linha e textos longos podem ocupar várias linhas. Isso torna arquivos de configuração e especificações de API mais fáceis de ler e editar. **Também conhecido como:** Estilo de bloco do YAML, Block style YAML, YAML em estilo de bloco, Notação de bloco YAML, YAML block style **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### Posso usar tabulação para indentar YAML em estilo de bloco? Não. A especificação do YAML não aceita tabulação para indentação. Use sempre espaços, de preferência dois por nível, e configure o editor de código para converter tabs em espaços automaticamente. ### Qual a diferença entre os indicadores | e >? O | (literal) mantém cada quebra de linha do texto original. O > (dobrado) une as linhas em um parágrafo só, substituindo as quebras por espaços. Use | quando a formatação importa e > para textos corridos longos. ### YAML em estilo de bloco pode ser convertido para JSON? Sim. Os dados representados são os mesmos, e bibliotecas comuns convertem YAML para JSON sem perda de estrutura. Atenção apenas a valores sem aspas que possam mudar de tipo, como códigos com zeros à esquerda. ### Quando devo colocar valores entre aspas? Sempre que o valor for um código que parece número (CNPJ, CEP, NCM), contiver dois-pontos, cerquilha ou começar com caracteres especiais, ou puder ser lido como verdadeiro ou falso, como sim, não, yes ou no. ## Termos relacionados - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [YAML block style](https://conota.dev/glossario/yaml-block-style/) · Atualizado em 2026-10-22 --- # YAML boolean > YAML boolean é o tipo de valor lógico usado em arquivos YAML para representar verdadeiro ou falso, normalmente escrito como true ou false. Em integrações fiscais, aparece em arquivos de configuração que ligam ou desligam recursos, como o uso do ambiente de homologação, e exige cuidado porque algumas versões interpretam yes, no, on e off como booleanos. **Também conhecido como:** Booleano em YAML, Valor booleano YAML, Boolean YAML, YAML boolean **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é um YAML boolean? YAML é um formato de texto usado para escrever configurações de forma legível, com chaves e valores organizados por recuo. Um boolean, ou booleano, é um valor que só pode ser verdadeiro ou falso, como um interruptor de liga e desliga. Em YAML, o booleano é escrito sem aspas: por exemplo, a linha homologacao: true indica que a opção está ativada, e enviar_email: false indica que está desativada. O programa que lê o arquivo entende esses valores como lógicos, e não como texto. ## Para que serve o booleano em arquivos YAML? Ele serve para controlar comportamentos de um sistema sem precisar alterar o código. Em projetos que se integram a uma API fiscal, é comum usar YAML para definir se a emissão será feita em homologação ou produção, se os PDFs devem ser gerados automaticamente ou se os registros detalhados de log estão ligados. Também aparece em especificações de APIs escritas em YAML, nas quais campos booleanos indicam, por exemplo, se um parâmetro é obrigatório (required: true). ## Quais palavras o YAML entende como verdadeiro ou falso? Na versão 1.2 da especificação YAML, os valores booleanos padrão são true e false, aceitando também variações de maiúsculas como True e FALSE. Na versão 1.1, ainda usada por várias bibliotecas, a lista é maior: yes, no, on, off, y e n também podem ser convertidos em booleanos. Por isso, o mesmo arquivo pode ser interpretado de formas diferentes dependendo da ferramenta que o lê. ## Quais erros comuns o YAML boolean pode causar? O problema mais conhecido é a conversão acidental: um valor que deveria ser texto vira booleano. Um campo como resposta: no, que deveria guardar a palavra no, pode ser lido como false. Esse caso ficou conhecido como o problema da Noruega, porque o código do país, NO, era convertido em falso. Em integrações fiscais, isso pode levar a configurações erradas, como uma opção de ambiente desligada sem querer ou um código lido incorretamente. A forma segura de evitar é colocar entre aspas tudo que for texto, por exemplo resposta: "no", e usar apenas true e false para valores lógicos. ## Qual a diferença entre booleano em YAML e em JSON? Em JSON, só existem true e false, sempre em minúsculas e sem aspas, o que deixa pouca margem para ambiguidade. Já o YAML é mais flexível e, por isso, mais sujeito a interpretações diferentes entre versões e bibliotecas. Como muitos sistemas convertem YAML em JSON antes de enviar dados a uma API, um booleano mal interpretado no YAML chega à API como valor lógico errado. Validar o resultado com um JSON Schema ajuda a detectar esse tipo de falha antes da emissão. ## Exemplos de YAML boolean - Um ERP usa um arquivo config.yaml com a linha usar_homologacao: true para que todas as notas de teste sejam enviadas ao ambiente de homologação antes da entrada em produção. - Uma especificação de API escrita em YAML define o campo gerar_pdf com type: boolean e default: true, indicando que o PDF do documento será gerado se nada for informado. - Um desenvolvedor descobre que a opção notificar: off foi interpretada como false pela biblioteca de leitura e troca o valor por notificar: false para deixar a intenção explícita. - Uma equipe passa a colocar entre aspas os códigos de texto do arquivo de configuração, como "NO" ou "00", para evitar conversões automáticas para booleano ou número. ## Perguntas frequentes ### Devo escrever true ou yes em YAML? Prefira true e false. Eles são reconhecidos em todas as versões do YAML e em JSON, enquanto yes, no, on e off só funcionam como booleanos em algumas bibliotecas, o que pode gerar comportamentos diferentes. ### Como impedir que um texto vire booleano no YAML? Coloque o valor entre aspas simples ou duplas, como "no" ou 'on'. Assim o leitor de YAML trata o conteúdo como texto, independentemente da versão da especificação usada. ### Colocar true entre aspas muda alguma coisa? Sim. "true" entre aspas é um texto, não um booleano. Se a API espera um valor lógico, enviar o texto pode causar erro de validação ou ser interpretado de forma inesperada. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [API fiscal](https://conota.dev/glossario/api-fiscal.md) --- Fonte: [YAML boolean](https://conota.dev/glossario/yaml-boolean/) · Atualizado em 2026-10-22 --- # YAML em configurações de implantação > YAML em configurações de implantação é o uso de arquivos de texto no formato YAML para descrever como um sistema deve ser instalado e executado: quais serviços sobem, com quais variáveis, em qual ambiente e com quais recursos. É comum em Kubernetes, Docker Compose e pipelines de integração contínua, incluindo integrações com APIs fiscais. **Também conhecido como:** Arquivo YAML de deploy, Manifesto YAML, Configuração em YAML, YML, YAML, YAML deployment configuration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML em configurações de implantação? YAML é um formato de texto feito para ser lido facilmente por pessoas e interpretado por programas. A sigla significa "YAML Ain't Markup Language". Em vez de chaves e colchetes, ele organiza as informações com recuos (espaços) e pares no formato chave: valor. Na implantação, ou deploy, esses arquivos funcionam como uma receita. Eles dizem à ferramenta de infraestrutura qual aplicação executar, quantas cópias manter, quais portas abrir e quais configurações carregar. Assim, o mesmo sistema pode ser publicado sempre da mesma forma, sem depender de passos manuais. ## Para que serve o YAML na implantação de uma integração fiscal? Em um ERP ou plataforma de vendas que emite NF-e, NFS-e ou NFC-e por API, o YAML costuma guardar as configurações do serviço responsável pela integração fiscal: o endereço da API, o tempo máximo de espera de cada requisição, a quantidade de tentativas em caso de falha e o ambiente usado. Uma vantagem prática é separar ambientes. É possível ter um arquivo para o ambiente de homologação, que gera documentos sem valor fiscal para testes, e outro para o ambiente de produção, que emite documentos válidos. Trocar de ambiente passa a ser uma mudança de configuração, e não de código. ## Como funciona a estrutura de um arquivo YAML? A base são pares de chave e valor, como timeout: 30. Para agrupar informações, usa-se recuo com espaços: tudo que está mais à direita pertence ao item acima. Listas são indicadas por um hífen no início da linha. Comentários começam com o caractere #. O recuo tem significado. Um espaço a mais ou a menos muda a estrutura e pode fazer a ferramenta ler a configuração de forma errada ou recusar o arquivo. Por isso, tabulações não são aceitas como recuo, apenas espaços. ## Qual a diferença entre YAML e JSON? Os dois representam o mesmo tipo de dado: objetos, listas, textos e números. Na verdade, quase todo JSON válido também é YAML válido. A diferença está na escrita: o JSON usa chaves, colchetes e aspas obrigatórias, enquanto o YAML depende de recuos e permite comentários. Na prática, o YAML é preferido para arquivos que pessoas editam com frequência, como configurações de implantação. Já o JSON é o formato mais comum para trocar dados entre sistemas, como no payload de uma requisição de emissão fiscal. ## Quais cuidados tomar ao usar YAML com dados fiscais e credenciais? O principal cuidado é nunca escrever segredos diretamente no arquivo, como a API Key, o token de autenticação ou a senha do certificado digital A1. Arquivos YAML costumam ir para repositórios de código e podem ser vistos por muitas pessoas. O ideal é que o YAML apenas faça referência a um segredo guardado em local protegido, como um Kubernetes Secret ou um cofre de chaves. Outro cuidado é com a interpretação automática de valores. Um CNPJ ou código de município que começa com zero pode ser lido como número e perder esse zero. Em algumas versões do formato, palavras como no ou yes viram valores verdadeiro ou falso. Colocar esses valores entre aspas garante que sejam tratados como texto. ## Exemplos de YAML em configurações de implantação - Um arquivo de Deployment do Kubernetes define a variável FISCAL_API_BASE_URL apontando para o endereço de homologação da API fiscal, enquanto um arquivo separado aponta para produção. - Um docker-compose.yml sobe localmente o backend de integração fiscal junto com o banco de dados e a fila de emissão, para que a equipe teste a emissão de NFS-e antes do deploy. - Um pipeline de integração contínua descrito em YAML executa testes de emissão em homologação e só libera a publicação em produção se todos passarem. - Um arquivo de configuração lista os CNPJs das filiais entre aspas, evitando que zeros à esquerda sejam removidos na leitura. ## Perguntas frequentes ### Posso colocar a API Key da emissão fiscal no arquivo YAML? Não é recomendado. O YAML deve apenas referenciar a chave, que precisa ficar em um local protegido, como um Kubernetes Secret, um cofre de chaves ou variáveis de ambiente gerenciadas. Isso reduz o risco de vazamento pelo repositório de código. ### Por que meu arquivo YAML dá erro mesmo parecendo correto? A causa mais comum é o recuo: uso de tabulação em vez de espaços ou quantidade de espaços inconsistente. Também vale conferir se há dois-pontos sem espaço depois e se textos com caracteres especiais estão entre aspas. ### A extensão é .yaml ou .yml? As duas são aceitas e representam o mesmo formato. A escolha costuma seguir o padrão da ferramenta ou da equipe. ## Termos relacionados - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) - [Kubernetes Secret](https://conota.dev/glossario/kubernetes-secret.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [JSON](https://conota.dev/glossario/json.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 em configurações de implantação](https://conota.dev/glossario/yaml-em-configuracoes-de-implantacao/) · Atualizado em 2026-10-22 --- # YAML em pipelines de integração > YAML em pipelines de integração é o uso de arquivos no formato YAML, um padrão de texto legível baseado em indentação, para descrever as etapas automáticas que testam, validam e publicam um sistema. Em integrações fiscais, esses arquivos definem, por exemplo, testes em homologação, variáveis de ambiente e implantação em produção. **Também conhecido como:** YAML em pipelines de CI/CD, Pipeline em YAML, Arquivo de pipeline YAML, Configuração de pipeline em YAML, YAML, YAML in CI/CD pipelines **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML e por que ele aparece em pipelines? YAML é um formato de texto usado para organizar informações em pares de chave e valor, listas e blocos aninhados. Em vez de chaves e colchetes, ele usa recuos (espaços no início da linha) para mostrar o que está dentro de quê. Isso o torna fácil de ler até para quem não programa. Um pipeline de integração é uma sequência automática de tarefas executada sempre que alguém altera o código: instalar dependências, rodar testes, gerar uma versão e publicá-la. A maioria das ferramentas de automação usa arquivos YAML para descrever essas tarefas, porque o formato é simples de versionar junto com o código e de revisar em equipe. ## Como funciona um pipeline descrito em YAML? O arquivo YAML fica guardado no repositório do projeto. Nele, a equipe declara quando o pipeline deve rodar (por exemplo, a cada alteração na branch principal), quais etapas existem, em que ordem acontecem e quais variáveis cada etapa recebe. Quando o gatilho acontece, a ferramenta de automação lê o arquivo e executa cada etapa em sequência ou em paralelo. Se uma etapa falha, como um teste de emissão que retorna erro, o pipeline para e avisa a equipe antes que o problema chegue aos clientes. ## Para que serve YAML em uma integração com API fiscal? Em sistemas que emitem NF-e, NFS-e, NFC-e, CT-e ou MDF-e por API, o pipeline em YAML ajuda a garantir que mudanças no código não quebrem a emissão. É comum incluir etapas que enviam payloads de teste ao ambiente de homologação, conferem se o status de retorno é o esperado e validam o XML recebido. O mesmo arquivo pode separar configurações por ambiente: em homologação, o sistema aponta para o endpoint de testes; em produção, para o endpoint real. Assim, a equipe evita emitir notas com valor fiscal por engano durante testes e mantém um histórico claro de cada alteração de configuração. ## Como lidar com certificados e chaves de API no arquivo YAML? Dados sensíveis, como API Key, token de autenticação, senha do certificado digital A1 ou o próprio certificado em Base64, nunca devem ser escritos diretamente no YAML. Como o arquivo fica no repositório, qualquer pessoa com acesso ao código veria essas informações. A prática correta é guardar esses valores em um cofre de segredos ou na área de segredos da ferramenta de automação e, no YAML, apenas referenciar o nome da variável. Na hora da execução, a ferramenta injeta o valor real sem expô-lo nos registros. Isso também facilita a troca periódica de chaves. ## Qual a diferença entre YAML e JSON? Os dois representam o mesmo tipo de estrutura de dados, e todo conteúdo JSON válido pode ser convertido para YAML. A diferença está na escrita: JSON usa chaves, colchetes e aspas obrigatórias, enquanto YAML depende de indentação e permite comentários, o que ajuda a documentar configurações. Na prática, JSON costuma ser o formato do payload enviado à API fiscal, por ser mais rígido e fácil de processar por máquinas. YAML é preferido em arquivos de configuração escritos e lidos por pessoas, como pipelines, manifestos de infraestrutura e especificações OpenAPI. ## Quais erros são comuns ao usar YAML em pipelines fiscais? O erro mais frequente é de indentação: misturar tabulações com espaços ou desalinhar uma linha muda o significado do arquivo ou o torna inválido. Editores com validação de YAML ajudam a evitar esse problema. Outro cuidado importante é com valores que parecem números. Códigos com zeros à esquerda, como uma série "001", um CEP ou um código de município, podem ser interpretados como número e perder os zeros. Colocar esses valores entre aspas garante que sejam tratados como texto e cheguem corretos à integração. ## Exemplos de YAML em pipelines de integração - Um ERP mantém um arquivo YAML que, a cada alteração no código, executa testes que emitem uma NF-e de exemplo no ambiente de homologação e só libera a nova versão se a nota for autorizada. - Uma plataforma de vendas define no YAML duas configurações de ambiente: uma variável com a URL de homologação para testes e outra com a URL de produção usada apenas na implantação final. - Um marketplace referencia no pipeline a variável que contém a API Key da emissão fiscal, armazenada no cofre de segredos, em vez de escrever a chave diretamente no arquivo. - Uma equipe descobre que o código de município de um teste de NFS-e perdia o zero inicial e corrige o YAML colocando o valor entre aspas. ## Perguntas frequentes ### Preciso saber programar para entender um arquivo YAML? Não necessariamente. YAML foi pensado para ser legível. Com noções de chave, valor, listas e indentação, já é possível entender a maior parte de um pipeline, embora alterá-lo com segurança exija algum conhecimento técnico. ### Posso guardar o certificado digital A1 dentro do YAML? Não. O certificado e sua senha devem ficar em um cofre de segredos ou na área de segredos da ferramenta de automação. O YAML apenas aponta para o nome da variável, que é preenchida no momento da execução. ### A API fiscal aceita requisições em YAML? Em geral, não. APIs fiscais costumam receber e devolver dados em JSON ou XML. O YAML é usado na configuração do pipeline e da infraestrutura, não no conteúdo enviado para emitir documentos. ### Por que testar a emissão no pipeline em vez de manualmente? Porque o teste automático roda sempre, do mesmo jeito, a cada alteração. Isso detecta rapidamente mudanças que causariam rejeições fiscais e reduz o risco de erros chegarem ao ambiente de produção. ## Termos relacionados - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Ambiente de produção](https://conota.dev/glossario/ambiente-de-producao.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [JSON](https://conota.dev/glossario/json.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) --- Fonte: [YAML em pipelines de integração](https://conota.dev/glossario/yaml-em-pipelines-de-integracao/) · Atualizado em 2026-10-22 --- # YAML flow style > YAML flow style é a forma compacta de escrever dados em YAML, usando chaves para mapas de chave e valor e colchetes para listas, geralmente em uma única linha, de modo parecido com JSON. Opõe-se ao block style, que organiza as informações por indentação, e aparece com frequência em arquivos de configuração e especificações de API. **Também conhecido como:** Flow style, Estilo de fluxo do YAML, Notação inline do YAML, Estilo em linha do YAML, YAML flow style **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML e onde entra o flow style? YAML é um formato de texto usado para representar dados de forma legível por pessoas. Ele é muito comum em arquivos de configuração de sistemas, ferramentas de automação e documentações de API. O YAML permite escrever a mesma informação de dois jeitos. O block style usa quebras de linha e indentação. O flow style usa delimitadores explícitos: chaves para objetos e colchetes para listas. Os dois estilos podem até ser misturados no mesmo arquivo. ## Como funciona a sintaxe do flow style? Um mapa, que é um conjunto de pares de chave e valor, fica entre chaves, com os pares separados por vírgula. Exemplo: empresa: {cnpj: "12345678000199", uf: SP}. Uma lista fica entre colchetes, com os itens separados por vírgula. Exemplo: documentos: [nfe, nfse, nfce]. As estruturas podem ser aninhadas, ou seja, colocadas umas dentro das outras: emissao: {ambiente: homologacao, tipos: [nfe, cte]}. Como os limites de cada estrutura são marcados pelos delimitadores, a indentação deixa de ser obrigatória dentro do trecho em flow style. ## Qual a diferença entre flow style e block style? No block style, cada informação costuma ocupar uma linha, e a hierarquia é indicada pelos espaços no início da linha. Isso deixa arquivos longos mais fáceis de ler e de comparar em revisões de código. No flow style, a informação fica concentrada em menos linhas. Ele funciona bem para listas curtas e objetos pequenos, mas fica difícil de ler quando a estrutura cresce. Por isso, muitos times usam block style como padrão e flow style apenas em trechos simples. ## Qual a relação entre YAML flow style e JSON? O flow style é muito parecido com JSON, que também usa chaves e colchetes. A partir da versão 1.2, o YAML foi pensado para ser compatível com JSON, de modo que um documento JSON comum normalmente também é um YAML válido. A diferença principal é que o YAML é mais flexível: aceita textos sem aspas, comentários iniciados por cerquilha e outras facilidades que o JSON não permite. Já as APIs fiscais costumam receber e devolver dados em JSON, enquanto o YAML aparece mais nos arquivos de configuração ao redor da integração. ## Onde o flow style aparece em integrações fiscais? Em projetos que emitem NF-e, NFS-e, NFC-e, CT-e ou MDF-e por API, o YAML costuma estar em arquivos de configuração do sistema, como a definição do ambiente de homologação ou produção, a lista de tipos de documento habilitados e os parâmetros de retentativa. Também é comum em especificações de API no formato OpenAPI e em pipelines de implantação. Nesses arquivos, o flow style aparece em trechos curtos, como listas de códigos de status HTTP tratados ou de UFs atendidas. ## Quais cuidados tomar ao usar flow style? Textos que contêm vírgula, dois-pontos, chaves ou colchetes precisam ficar entre aspas, porque esses caracteres têm significado especial no flow style. Sem aspas, o arquivo pode ser interpretado de forma errada ou nem ser lido. Códigos fiscais e cadastrais, como CNPJ, CEP, CFOP e inscrição estadual, devem ser escritos entre aspas para serem tratados como texto. Assim se evita que zeros à esquerda sejam perdidos ou que o valor vire número. Também não é recomendável guardar API Keys ou senhas de certificado em arquivos YAML versionados; o ideal é usar uma ferramenta de gerenciamento de segredos. ## Exemplos de YAML flow style - Arquivo de configuração de um ERP com a linha documentos_habilitados: [nfe, nfce, nfse], indicando quais documentos o sistema enviará para a API fiscal. - Configuração de retentativas escrita como retry: {tentativas: 5, espera_inicial_ms: 500, status: [429, 502, 503]}, usada pelo backend de integração ao reenviar requisições. - Especificação OpenAPI de um serviço interno que descreve um campo de ambiente com enum: [homologacao, producao] em flow style. - Cadastro de filial em YAML escrito como filial: {cnpj: "12345678000199", ie: "0123456789", uf: MG}, com aspas para preservar os zeros à esquerda. ## Perguntas frequentes ### Posso enviar YAML em vez de JSON para uma API fiscal? Depende da API. A maioria das APIs REST de emissão fiscal trabalha com JSON, informado no header Content-Type. Se a documentação não indicar suporte a YAML, converta os dados para JSON antes de enviar. ### Flow style e block style podem ser usados no mesmo arquivo? Sim. É comum usar block style para a estrutura principal e flow style em listas ou objetos curtos. O importante é manter a sintaxe correta em cada trecho. ### Por que colocar o CNPJ entre aspas no YAML? Sem aspas, o CNPJ pode ser lido como número, o que pode remover zeros à esquerda ou alterar o valor. Com aspas, ele é tratado como texto e chega íntegro ao sistema. ### O flow style aceita comentários? O YAML aceita comentários iniciados por cerquilha, mas eles devem ficar no fim da linha ou em linhas próprias, fora de valores entre aspas. Em trechos longos de flow style, comentários tendem a prejudicar a leitura. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Header Content-Type](https://conota.dev/glossario/header-content-type.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [YAML flow style](https://conota.dev/glossario/yaml-flow-style/) · Atualizado em 2026-10-22 --- # YAML folded scalar > YAML folded scalar é um estilo de escrita de textos longos em arquivos YAML, indicado pelo símbolo maior que (>), no qual as quebras de linha do texto são convertidas em espaços na leitura. Assim, um parágrafo extenso pode ser distribuído em várias linhas no arquivo, mantendo legibilidade, e ser interpretado como uma única linha contínua. **Também conhecido como:** Folded block scalar, Escalar dobrado, Bloco dobrado do YAML, Estilo folded, Folded style, YAML folded scalar **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## Como funciona o folded scalar no YAML? YAML é um formato de texto usado para escrever configurações e especificações de forma legível para pessoas. Quando um valor de texto é muito longo, o YAML oferece os chamados escalares de bloco, e o folded scalar é um deles. Ele começa com o sinal > logo após a chave, e o texto vem nas linhas seguintes, com recuo. Na hora da leitura, o programa que interpreta o arquivo junta as linhas do bloco, trocando cada quebra de linha simples por um espaço. Se houver uma linha em branco entre dois trechos, ela vira uma quebra de linha de verdade. Na prática, é como escrever parágrafos: linhas consecutivas formam uma frase só, e linhas vazias separam parágrafos. Por exemplo, uma chave descricao seguida de > e, abaixo, as linhas recuadas 'Endpoint que emite' e 'uma NFS-e' resulta no texto 'Endpoint que emite uma NFS-e', em uma única linha. ## Qual a diferença entre folded scalar (>) e literal scalar (|)? O literal scalar, marcado com a barra vertical (|), preserva todas as quebras de linha exatamente como foram escritas. Já o folded scalar, marcado com >, dobra as linhas em espaços. Os dois servem para textos de várias linhas, mas produzem resultados diferentes. A regra prática é: use > para textos corridos, como descrições e mensagens, em que a quebra de linha só existe para facilitar a leitura no arquivo. Use | quando a quebra de linha faz parte do conteúdo, como em trechos de XML, scripts, chaves em formato PEM ou qualquer texto em que juntar as linhas mudaria o significado. ## O que significam os indicadores >- e >+? Depois do sinal >, pode vir um indicador que controla o que acontece com as quebras de linha no final do bloco, chamado de chomping. Sem indicador, o YAML mantém exatamente uma quebra de linha no fim do texto. Com >- (sinal de menos), todas as quebras finais são removidas, e o texto termina sem nenhuma nova linha. Com >+ (sinal de mais), todas as quebras e linhas vazias do final são mantidas. O >- é muito comum quando o valor será comparado ou enviado como está, porque evita uma quebra de linha invisível no fim da string. ## Onde o folded scalar aparece em integrações fiscais por API? Equipes que integram sistemas próprios a uma API fiscal encontram YAML em vários lugares: especificações OpenAPI que documentam endpoints, arquivos de configuração de serviços, pipelines de implantação e manifestos de infraestrutura. Nesses arquivos, o folded scalar é usado principalmente para descrições longas de endpoints, campos e mensagens. Um exemplo típico é a descrição de um campo de discriminação de serviços na especificação de um endpoint de emissão de NFS-e, ou um texto explicando as regras de cancelamento de uma NF-e. Escrever com > deixa o arquivo organizado sem inserir quebras de linha indesejadas no texto final exibido na documentação. ## Quais cuidados tomar ao usar o folded scalar? O recuo é obrigatório e deve ser feito com espaços, nunca com tabulação, porque o YAML não aceita tabulações para indentação. Todas as linhas do bloco precisam ter pelo menos o mesmo recuo da primeira; uma linha com recuo menor encerra o bloco. Linhas com recuo maior que as demais dentro de um bloco dobrado não são juntadas, e suas quebras de linha são preservadas, o que costuma surpreender quem não conhece a regra. Também é importante não usar > para conteúdos sensíveis à formatação, como certificados, XML assinado ou valores que entram em cálculos de hash, pois a troca de quebras por espaços altera o conteúdo e pode invalidar o resultado. ## Exemplos de YAML folded scalar - Em uma especificação OpenAPI de um endpoint de emissão de NF-e, a chave description usa > para explicar em várias linhas do arquivo que a requisição é processada de forma assíncrona e que o status deve ser consultado depois, gerando na documentação um único parágrafo contínuo. - Um arquivo de configuração de um serviço de integração fiscal define a mensagem exibida ao usuário quando a SEFAZ rejeita uma nota, usando >- para que o texto final não termine com uma quebra de linha extra. - Uma equipe percebe que a chave privada guardada em YAML com > deixou de funcionar, porque as quebras de linha do formato PEM viraram espaços; ao trocar para | o conteúdo volta a ser lido corretamente. - Em um manifesto de implantação, a descrição de uma variável de ambiente que aponta para o ambiente de homologação é escrita com > em várias linhas curtas, facilitando a revisão do arquivo sem alterar o valor lido pela aplicação. ## Perguntas frequentes ### O folded scalar remove todas as quebras de linha? Não. Ele troca quebras simples por espaços, mas linhas em branco viram quebras de linha reais, e linhas com recuo maior mantêm suas quebras. No final do bloco, o comportamento depende do indicador: >, >- ou >+. ### Posso usar folded scalar para guardar um XML fiscal em YAML? Não é recomendado. Juntar linhas pode alterar o conteúdo e invalidar assinaturas digitais ou hashes. Para textos em que a formatação importa, use o literal scalar (|) ou, melhor ainda, armazene o arquivo separadamente. ### Existe equivalente do folded scalar em JSON? Não. Em JSON, uma string precisa ficar em uma única linha, com quebras representadas por n. O folded scalar é um recurso exclusivo do YAML para facilitar a leitura de textos longos no arquivo. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [YAML folded scalar](https://conota.dev/glossario/yaml-folded-scalar/) · Atualizado em 2026-10-22 --- # YAML literal scalar > YAML literal scalar é a forma de escrever textos de várias linhas em arquivos YAML preservando exatamente as quebras de linha. Indicado pelo caractere barra vertical (|), é muito usado em configurações de integrações, por exemplo para guardar certificados em formato PEM, scripts e mensagens longas sem precisar de caracteres de escape. **Também conhecido como:** Bloco literal YAML, Escalar literal, Literal block scalar, Block scalar literal, Bloco com barra vertical, YAML literal block scalar **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é um YAML literal scalar? YAML é um formato de arquivo de texto usado para escrever configurações de forma legível, com chaves e valores organizados por indentação. Um scalar, em YAML, é simplesmente um valor único, como um número ou um texto. O literal scalar é um tipo especial de valor de texto, também chamado de bloco literal. Ele permite escrever um conteúdo de várias linhas exatamente como ele deve ser lido pelo sistema, mantendo cada quebra de linha no lugar. Para indicar esse modo, coloca-se uma barra vertical (|) logo após a chave, e o texto começa na linha seguinte, com recuo. ## Como funciona o literal scalar na prática? Imagine a chave observacao seguida de dois-pontos e da barra vertical. Nas linhas de baixo, com alguns espaços de recuo, você escreve o texto. Tudo o que estiver recuado faz parte do valor, e cada nova linha do arquivo vira uma nova linha no texto final. O recuo da primeira linha define a margem do bloco: esses espaços iniciais são descartados, mas qualquer recuo extra é mantido. O bloco termina quando aparece uma linha com recuo menor, normalmente a próxima chave do arquivo. Dentro do bloco, caracteres como aspas, dois-pontos e barras invertidas não precisam de escape. ## Para que serve o literal scalar em integrações fiscais? Em sistemas que se integram a uma API fiscal, arquivos YAML aparecem em configurações de servidores, pipelines de implantação, documentações de API e ferramentas de orquestração. O literal scalar é útil sempre que um valor precisa manter sua formatação original. Um caso comum é guardar o conteúdo de um certificado ou chave em formato PEM, que exige quebras de linha corretas para ser lido. Outros usos são scripts de comandos, modelos de mensagens, textos padrão de informações complementares e descrições longas em especificações de API. Se as quebras de linha se perderem, o conteúdo pode ficar inválido ou mal formatado. ## Qual a diferença entre literal scalar (|) e folded scalar (>)? Os dois servem para escrever textos de várias linhas, mas tratam as quebras de linha de forma diferente. O literal (|) mantém cada quebra exatamente como está no arquivo. O folded (>), ou dobrado, junta as linhas em um único parágrafo, trocando as quebras simples por espaços; apenas linhas em branco viram quebras de verdade. Na prática, use o literal quando a formatação importa, como em certificados, scripts e textos com linhas separadas. Use o folded quando quiser apenas quebrar um texto longo no arquivo para facilitar a leitura, sem que essas quebras apareçam no resultado. ## O que significam |-, |+ e números depois da barra? Logo após a barra vertical podem aparecer indicadores que controlam o final do texto. Sem indicador, o YAML mantém uma única quebra de linha no fim do bloco. Com |- (strip), todas as quebras finais são removidas. Com |+ (keep), todas as quebras e linhas em branco finais são preservadas. Também é possível colocar um número, como |2, para informar explicitamente quantos espaços formam a margem do bloco. Isso é útil quando a primeira linha do texto começa com espaços que devem fazer parte do conteúdo. Esses detalhes importam, por exemplo, quando um sistema compara textos ou valida assinaturas e uma quebra de linha a mais muda o resultado. ## Quais cuidados tomar ao usar literal scalar? O erro mais frequente é misturar tabulações e espaços ou errar o recuo, o que encerra o bloco antes da hora ou gera erro de leitura. Editores com destaque de sintaxe YAML ajudam a evitar esse problema. Outro cuidado é com informações sensíveis. Colocar chaves privadas, senhas de certificados ou API Keys diretamente em arquivos YAML versionados é arriscado. O ideal é que o YAML apenas referencie esses valores, que ficam guardados em um cofre ou serviço de gerenciamento de segredos. ## Exemplos de YAML literal scalar - Uma equipe configura o servidor do seu ERP e usa a chave certificado_pem seguida de | para inserir o conteúdo de um certificado em formato PEM, preservando as linhas de início, fim e o corpo do certificado. - Na especificação OpenAPI de um backend de integração fiscal, o campo description de um endpoint de emissão de NFS-e usa | para listar, linha por linha, os passos do fluxo assíncrono e os possíveis status de retorno. - Um pipeline de implantação em YAML usa run: | para executar vários comandos em sequência, como instalar dependências, rodar testes no ambiente de homologação e publicar a nova versão da integração. - Um arquivo de configuração guarda o texto padrão de informações complementares das notas com |- para manter as linhas separadas e evitar uma quebra de linha extra no final. ## Perguntas frequentes ### O literal scalar altera o conteúdo do texto? Não altera o texto em si. Ele remove apenas o recuo de margem do bloco e mantém as quebras de linha. O único ajuste automático é no final, controlado pelos indicadores: sem indicador fica uma quebra final, com |- nenhuma e com |+ todas. ### Posso usar literal scalar para guardar um arquivo PFX? O PFX é binário, então não pode ser colado diretamente como texto. Ele precisa antes ser convertido para Base64. Mesmo assim, guardar o certificado em YAML versionado não é recomendado; prefira um serviço de gerenciamento de segredos. ### Existe algo equivalente ao literal scalar em JSON? Não. Em JSON, textos de várias linhas precisam ficar em uma única linha, com as quebras representadas por n. Por isso o YAML costuma ser preferido em configurações escritas à mão que contêm textos longos ou formatados. ## Termos relacionados - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Base64 no envio de certificados](https://conota.dev/glossario/base64-no-envio-de-certificados.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Backend de integração fiscal](https://conota.dev/glossario/backend-de-integracao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) --- Fonte: [YAML literal scalar](https://conota.dev/glossario/yaml-literal-scalar/) · Atualizado em 2026-10-22 --- # YAML mapping > YAML mapping é a estrutura do formato YAML que organiza dados em pares de chave e valor, como "ambiente: producao". Cada chave é única e aponta para um valor, que pode ser texto, número, lista ou outro mapping. Equivale a um objeto em JSON e aparece em arquivos de configuração e especificações de APIs. **Também conhecido como:** Mapeamento YAML, Mapa YAML, Dicionário YAML, Objeto YAML, Hash YAML, YAML mapping **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é um YAML mapping? YAML é um formato de texto para representar dados de um jeito fácil de ler por pessoas. Dentro dele, o mapping, ou mapeamento, é o bloco que associa nomes (chaves) a informações (valores). Na forma mais comum, cada linha traz uma chave, dois-pontos, um espaço e o valor, como em "serie: 1". Um mapping pode conter outros mappings dentro dele. Isso é indicado pela indentação, ou seja, pelos espaços no início da linha. Assim, uma chave "emitente" pode agrupar abaixo dela as chaves "cnpj" e "inscricao_estadual", formando uma estrutura em níveis, parecida com pastas dentro de pastas. ## Para que serve o YAML mapping em integrações fiscais? Em projetos de emissão fiscal por API, o YAML costuma aparecer menos no envio dos documentos e mais na configuração e na documentação. Especificações OpenAPI, que descrevem endpoints, campos e respostas de uma API, são frequentemente escritas em YAML, e cada objeto descrito ali é um mapping. Também é comum usar mappings em arquivos de configuração do sistema integrador, por exemplo para definir o ambiente de homologação ou de produção, a série padrão de cada documento e o tempo limite das requisições. Em infraestruturas com Kubernetes, os manifestos que declaram serviços e segredos são inteiramente compostos por mappings. ## Como se escreve um YAML mapping? Há dois estilos. O estilo em bloco, mais usado, coloca um par por linha e usa indentação com espaços para indicar níveis. O estilo em fluxo coloca tudo em uma linha entre chaves, como em {ambiente: homologacao, serie: 1}, de forma bem parecida com JSON. Algumas regras básicas: a indentação deve ser feita com espaços, nunca com tabulação; deve haver um espaço depois dos dois-pontos; e a mesma chave não deve se repetir no mesmo nível. Comentários podem ser incluídos com o caractere # e são ignorados na leitura. ## Qual a diferença entre YAML mapping e objeto JSON? Na prática, representam a mesma ideia: um conjunto de pares chave e valor. A diferença está na escrita. O JSON exige chaves entre aspas, uso de chaves e vírgulas, e não aceita comentários. O YAML dispensa boa parte dessa pontuação e usa a indentação para mostrar a estrutura. Por isso, é comum converter um no outro sem perda de informação. Muitas APIs fiscais recebem o payload em JSON, mas a equipe pode manter exemplos ou configurações em YAML e convertê-los antes do envio. Vale lembrar que, em um mapping, a ordem das chaves não deve ser tratada como significativa. ## Quais cuidados evitam erros com YAML mapping em dados fiscais? O YAML tenta adivinhar o tipo de cada valor. Isso pode causar problemas com códigos fiscais que começam com zero, como CEP, CNPJ, código de município ou alguns códigos de produto: dependendo do leitor, eles podem ser tratados como número, perdendo os zeros à esquerda. A solução é colocar esses valores entre aspas, como em cep: "01310100". Outro ponto de atenção são palavras como yes, no, on e off, que em algumas versões e bibliotecas de YAML são interpretadas como verdadeiro ou falso. Também é importante revisar a indentação, pois um espaço a mais ou a menos muda a qual mapping uma chave pertence e pode gerar um payload com campos no lugar errado. ## Exemplos de YAML mapping - Uma especificação OpenAPI em YAML descreve o corpo da requisição de emissão de NF-e com um mapping "properties", que lista campos como "natureza_operacao", "destinatario" e "itens", cada um com seu tipo. - Um arquivo de configuração do ERP usa o mapping {ambiente: homologacao, timeout_segundos: 30, serie_nfe: "1"} para testar a integração antes de passar para produção. - Um manifesto de Kubernetes Secret, escrito em YAML, contém um mapping "data" que guarda a API Key usada pelo backend para autenticar as chamadas à API fiscal. - Uma equipe mantém exemplos de payload de NFS-e em YAML para facilitar a leitura e converte esses mappings para JSON antes de enviá-los ao endpoint de emissão. ## Perguntas frequentes ### YAML mapping é a mesma coisa que dicionário? Sim, na prática. Em linguagens de programação, um mapping YAML costuma ser lido como dicionário, mapa, hash ou objeto, dependendo da linguagem. Em todos os casos, trata-se de uma coleção de pares chave e valor com chaves únicas. ### Posso enviar YAML diretamente para uma API fiscal? Depende da API. A maioria das APIs REST de emissão fiscal recebe JSON. Nesse caso, o mapping YAML precisa ser convertido para objeto JSON antes do envio, o que bibliotecas comuns fazem automaticamente. ### Por que meu CNPJ perdeu o zero inicial no YAML? Porque o leitor de YAML interpretou o valor como número. Para preservar zeros à esquerda em CNPJ, CEP, códigos de município ou inscrições, escreva o valor entre aspas, garantindo que seja tratado como texto. ### Tabulação funciona na indentação do YAML? Não. A especificação do YAML não permite tabulação para indentar a estrutura. Use sempre espaços e mantenha a mesma quantidade em cada nível para evitar erros de leitura. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Kubernetes Secret](https://conota.dev/glossario/kubernetes-secret.md) - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) --- Fonte: [YAML mapping](https://conota.dev/glossario/yaml-mapping/) · Atualizado em 2026-10-22 --- # YAML multi-document stream > YAML multi-document stream é um arquivo ou fluxo de texto no formato YAML que reúne vários documentos independentes, separados pela marcação de três hifens (---). Cada documento é lido como um bloco de dados próprio. Isso permite guardar, por exemplo, várias configurações da infraestrutura de uma API fiscal em um único arquivo organizado. **Também conhecido como:** YAML multidocumento, Stream YAML com múltiplos documentos, Arquivo YAML com vários documentos, YAML multi-document, YAML multi-document stream **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é um YAML multi-document stream? YAML é um formato de texto usado para escrever dados e configurações de forma legível por pessoas. Ele organiza as informações com indentação, ou seja, com espaços no início das linhas, em vez de chaves e colchetes como no JSON. Normalmente, um arquivo YAML contém um único documento. Em um multi-document stream, o mesmo arquivo carrega vários documentos, um depois do outro. Para o programa que lê o arquivo, cada parte funciona como se fosse um arquivo separado, embora todas estejam juntas no mesmo lugar. ## Como funciona a separação entre os documentos? O início de cada documento é marcado por uma linha contendo apenas três hifens (—). Tudo o que vem depois dessa linha, até o próximo separador, pertence ao mesmo documento. O primeiro separador é opcional quando o arquivo começa direto com os dados. A especificação do YAML também prevê uma marcação opcional de fim de documento, com três pontos (…), pouco usada no dia a dia. Comentários, iniciados com o caractere #, podem aparecer em qualquer parte e não são considerados dados. ## Para que serve em integrações e infraestrutura de APIs fiscais? O uso mais comum aparece na configuração de infraestrutura. Em ambientes com Kubernetes, por exemplo, é frequente reunir em um só arquivo a definição da aplicação, do serviço de rede e de outros recursos de um backend de integração fiscal, aplicando tudo de uma vez. Também é útil para manter juntas configurações relacionadas, como os parâmetros de um mesmo serviço em homologação e em produção, ou definições separadas para cada empresa emissora. Isso facilita revisar alterações, versionar o arquivo e evitar que configurações fiquem espalhadas. ## Qual a diferença entre vários documentos e um documento com uma lista? Um único documento YAML pode conter uma lista de itens, e isso às vezes parece equivalente a vários documentos. A diferença está em como o programa interpreta o conteúdo: uma lista é um único dado com vários elementos; um stream com vários documentos entrega dados independentes, lidos um a um. Na prática, ferramentas como o Kubernetes esperam que cada recurso seja um documento próprio. Já uma aplicação que lê uma lista de configurações costuma esperar um único documento. Escolher o formato errado pode fazer o arquivo ser rejeitado ou lido pela metade. ## Quais cuidados tomar ao usar arquivos YAML com vários documentos? Muitas bibliotecas de leitura de YAML têm uma função para ler um documento e outra para ler vários. Se o sistema usar a função de documento único em um stream, pode gerar erro ou ignorar o restante. Vale confirmar qual função a biblioteca adotada oferece. Outro cuidado é com informações sensíveis. Arquivos de configuração costumam ser versionados e compartilhados, então senhas, API Keys e certificados digitais não devem ficar em texto aberto. O ideal é referenciar um cofre ou serviço de gerenciamento de segredos. A indentação também exige atenção: um espaço a mais ou a menos muda o significado dos dados. ## Existe algo equivalente no formato JSON? O JSON padrão não tem um separador nativo para vários documentos em um único arquivo. Uma alternativa comum é o formato JSON Lines, em que cada linha contém um objeto JSON completo, muito usado em logs e exportações de dados. Como o JSON é amplamente usado no envio de dados para APIs, e o YAML é mais comum em arquivos de configuração, é normal que um mesmo projeto de integração fiscal utilize os dois formatos, cada um em seu papel. ## Exemplos de YAML multi-document stream - Uma equipe de tecnologia mantém um arquivo chamado emissor-fiscal.yaml com três documentos separados por —: um descreve a aplicação que consome a API fiscal, outro o serviço de rede e outro a referência ao segredo que guarda a API Key. - Um ERP guarda em um único arquivo YAML dois documentos de configuração: um com o endereço e os parâmetros do ambiente de homologação e outro com os do ambiente de produção, carregando apenas o documento correspondente ao ambiente em uso. - Uma plataforma que emite notas para vários CNPJs mantém um stream YAML com um documento por empresa, contendo série, regime tributário e tipos de documento habilitados, lido em sequência na inicialização do sistema. - Um desenvolvedor recebe erro ao carregar a configuração porque a biblioteca estava usando a função de leitura de documento único; ao trocar pela função de leitura múltipla, todos os documentos do arquivo passam a ser processados. ## Perguntas frequentes ### Os três hifens no início do arquivo são obrigatórios? Não. Se o arquivo tem apenas um documento ou começa direto com os dados, o primeiro separador pode ser omitido. A partir do segundo documento, porém, a linha com --- é necessária para indicar onde cada um começa. ### Posso enviar um YAML multi-document para uma API fiscal? Em geral, não. APIs de emissão fiscal costumam receber o payload em JSON ou XML, conforme a documentação. O YAML multi-document é mais usado em configurações e infraestrutura, não no envio dos dados de uma nota. ### Cada documento do stream pode ter uma estrutura diferente? Sim. Os documentos são independentes, então cada um pode ter campos e formatos próprios. Cabe ao programa que lê o arquivo saber interpretar cada tipo de documento recebido. ### É seguro guardar certificados e senhas nesses arquivos? Não é recomendado guardá-los em texto aberto. O mais seguro é armazenar segredos em um cofre ou serviço específico e deixar no arquivo YAML apenas a referência a eles. ## Termos relacionados - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) - [Kubernetes Secret](https://conota.dev/glossario/kubernetes-secret.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [JSON](https://conota.dev/glossario/json.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Backend de integração fiscal](https://conota.dev/glossario/backend-de-integracao-fiscal.md) --- Fonte: [YAML multi-document stream](https://conota.dev/glossario/yaml-multi-document-stream/) · Atualizado em 2026-10-22 --- # YAML na documentação de APIs > YAML na documentação de APIs é o uso do formato de texto YAML para descrever, de forma legível por pessoas e por máquinas, como uma API funciona: endpoints, parâmetros, formatos de requisição e resposta, autenticação e erros. É muito usado em especificações OpenAPI, que alimentam ferramentas como o Swagger UI e geradores de código. **Também conhecido como:** YAML, YML, Especificação de API em YAML, Arquivo YAML da API, YAML in API documentation **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML? YAML é um formato de texto para organizar dados de forma estruturada. O nome é um acrônimo recursivo em inglês, YAML Ain't Markup Language, que indica que ele foi pensado para representar dados, e não para formatar documentos como o HTML. A principal característica do YAML é a leitura fácil. Em vez de chaves, colchetes e muitas aspas, ele usa recuo (espaços no início da linha) para mostrar o que está dentro do quê. Um item como status: autorizado já é um par de nome e valor válido. Por isso, o YAML é muito usado em arquivos de configuração e, principalmente, na escrita de especificações de APIs. ## Para que serve o YAML na documentação de APIs? Ele serve para escrever a especificação de uma API em um único arquivo que descreve tudo o que um desenvolvedor precisa saber: quais endpoints existem, quais métodos HTTP aceitam, quais campos devem ser enviados, quais respostas podem voltar e como autenticar. O formato mais comum para isso é a especificação OpenAPI, que pode ser escrita em YAML ou em JSON. Muitas equipes preferem YAML porque o arquivo fica mais curto e mais fácil de revisar. Como o arquivo é lido também por programas, ele pode gerar automaticamente uma documentação navegável (como no Swagger UI), coleções de teste, validações de payload e até bibliotecas cliente em várias linguagens. ## Como é a estrutura de um arquivo YAML? O YAML se baseia em três ideias simples: pares de chave e valor (nome: valor), listas (linhas que começam com hífen) e aninhamento por recuo. Se um campo está mais recuado que o anterior, ele pertence a esse anterior. Por exemplo, em uma especificação OpenAPI, a linha paths: abre a lista de rotas; logo abaixo, mais recuada, vem uma rota como /nfe; dentro dela, o método post:; e dentro do método, a descrição dos campos aceitos e das respostas possíveis. Comentários são escritos depois do símbolo #, o que ajuda a explicar decisões dentro do próprio arquivo, algo que o JSON não permite. ## Qual a diferença entre YAML e JSON? Os dois representam os mesmos tipos de dados: textos, números, valores verdadeiro ou falso, listas e objetos. Na prática, quase todo JSON válido também é aceito como YAML, e é possível converter um no outro sem perder informação. A diferença está na forma. O JSON usa chaves, colchetes e aspas obrigatórias, é mais rígido e é o formato padrão na troca de dados entre sistemas, como no envio de uma nota fiscal para uma API. O YAML é mais enxuto, aceita comentários e é preferido para arquivos escritos e mantidos por pessoas, como especificações e configurações. Em resumo: a API fiscal normalmente recebe e devolve JSON, enquanto a documentação que descreve essa API costuma ser escrita em YAML. ## Quais cuidados tomar ao usar YAML em APIs fiscais? O recuo precisa ser feito com espaços, nunca com tabulação, e deve ser consistente. Um espaço a mais ou a menos muda o significado do arquivo ou causa erro de leitura. Códigos fiscais exigem atenção especial. Valores como CST 00, códigos com zero à esquerda ou números longos, como NCM e código de município, podem ser interpretados como número e perder os zeros. O ideal é colocá-los entre aspas e declarar o tipo como string no esquema. Também vale manter a especificação sincronizada com a API real. Se um campo novo for exigido por uma nota técnica e o YAML não for atualizado, quem integra vai receber erros de validação sem entender o motivo. ## Exemplos de YAML na documentação de APIs - Um ERP baixa o arquivo OpenAPI em YAML de uma API fiscal e usa um gerador de código para criar automaticamente as funções de emissão de NF-e e consulta de status. - A equipe de integração abre o arquivo YAML no Swagger UI para visualizar o endpoint de emissão de NFS-e, conferir os campos obrigatórios do tomador e testar uma chamada no ambiente de homologação. - Um desenvolvedor descreve no YAML o campo de código do município como string entre aspas, evitando que valores numéricos longos sejam tratados como número e quebrem a validação. - Uma plataforma de vendas inclui comentários no YAML da sua API interna explicando que o campo de série da NFC-e segue a configuração cadastrada para cada CNPJ emissor. ## Perguntas frequentes ### Preciso saber YAML para integrar uma API fiscal? Não necessariamente. O YAML costuma descrever a API, mas as requisições em geral usam JSON. Saber ler o básico ajuda a entender a especificação, mas ferramentas como o Swagger UI já mostram essas informações de forma visual. ### Uma especificação OpenAPI em YAML e em JSON é a mesma coisa? Sim, em conteúdo. São duas formas de escrever as mesmas informações. É possível converter de uma para a outra sem perda, e as ferramentas compatíveis com OpenAPI aceitam ambos os formatos. ### Por que meu arquivo YAML dá erro de leitura? Os motivos mais comuns são uso de tabulação no recuo, recuo inconsistente entre linhas, dois-pontos sem espaço depois e caracteres especiais em textos sem aspas. Um validador de YAML aponta a linha com problema. ### Qual extensão um arquivo YAML usa? As extensões mais comuns são .yaml e .yml. As duas funcionam da mesma forma; a escolha é apenas uma convenção do projeto. ## Termos relacionados - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Swagger UI](https://conota.dev/glossario/swagger-ui.md) - [JSON](https://conota.dev/glossario/json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) --- Fonte: [YAML na documentação de APIs](https://conota.dev/glossario/yaml-na-documentacao-de-apis/) · Atualizado em 2026-10-22 --- # YAML na especificação OpenAPI > YAML na especificação OpenAPI é o formato de texto, baseado em indentação e pares chave-valor, usado para escrever o documento que descreve uma API: seus endpoints, parâmetros, formatos de requisição e resposta e regras de autenticação. Por ser legível para pessoas e máquinas, facilita documentar, revisar e gerar código para integrações, como APIs fiscais. **Também conhecido como:** OpenAPI em YAML, Arquivo openapi.yaml, Especificação OpenAPI em formato YAML, Swagger em YAML, YAML, YAML in the OpenAPI Specification **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é YAML e por que ele aparece na OpenAPI? YAML é um formato de texto para organizar dados de forma estruturada. O nome é um acrônimo recursivo de "YAML Ain't Markup Language". Em vez de chaves e colchetes, ele usa recuos (espaços no começo da linha) para mostrar o que está dentro de quê, o que deixa o arquivo parecido com uma lista escrita à mão. A OpenAPI é um padrão para descrever APIs REST. Ela aceita dois formatos para esse documento: JSON e YAML. Muitas equipes escolhem o YAML porque ele é mais fácil de ler e editar, especialmente quando a descrição da API fica longa, com dezenas de endpoints e campos. ## Como é a estrutura de um arquivo OpenAPI em YAML? O arquivo, normalmente chamado de openapi.yaml, começa indicando a versão do padrão no campo openapi. Em seguida vem o bloco info, com título, descrição e versão da API. O bloco paths lista cada endpoint, como um caminho para emitir uma NF-e, e diz quais métodos HTTP ele aceita, quais parâmetros recebe e quais respostas pode devolver. Há também o bloco components, onde ficam definições reutilizáveis: os schemas (o formato de cada objeto, como emitente, destinatário ou item da nota), os esquemas de segurança (por exemplo, Bearer token ou API Key) e respostas de erro padronizadas. Para reaproveitar uma definição, usa-se uma referência com $ref, evitando repetir o mesmo conteúdo em vários lugares. ## Qual a diferença entre usar YAML ou JSON na OpenAPI? Em conteúdo, nenhuma: os dois formatos descrevem exatamente a mesma API e podem ser convertidos um no outro sem perda de informação. A diferença está na forma. O JSON usa chaves, colchetes e aspas em todos os nomes; o YAML usa recuos e dispensa boa parte da pontuação. O YAML também permite comentários com o caractere #, algo que o JSON não aceita. Isso ajuda a explicar regras de negócio dentro do próprio arquivo. Por outro lado, o JSON é menos sujeito a erros de interpretação, e por isso muitas ferramentas geram ou consomem a especificação nesse formato. Na prática, é comum escrever em YAML e publicar nos dois. ## Para que serve o YAML da OpenAPI em uma integração fiscal? Para quem integra um ERP, uma plataforma de vendas ou um marketplace a uma API fiscal, o arquivo OpenAPI funciona como o contrato da integração. Ele mostra quais campos são obrigatórios no payload de emissão, quais formatos são aceitos e quais status e erros podem voltar, como uma rejeição fiscal. Com esse arquivo, ferramentas como o Swagger UI geram uma documentação interativa, em que é possível testar chamadas no ambiente de homologação. Também é possível gerar automaticamente bibliotecas cliente em várias linguagens e validar se as requisições do sistema estão no formato esperado antes de enviá-las. ## Quais cuidados tomar ao escrever YAML na OpenAPI? O principal cuidado é com a indentação: o YAML não aceita tabulação, apenas espaços, e um recuo errado muda o significado do arquivo ou o torna inválido. Editores com validação de OpenAPI ajudam a encontrar esses problemas rapidamente. Outro ponto importante para dados fiscais é a tipagem. Valores como CNPJ, CEP, NCM, CFOP ou códigos de município parecem números, mas devem ser tratados como texto, pois zeros à esquerda não podem ser perdidos. Por isso, nos schemas, esses campos devem ser declarados com type string, e exemplos com zeros à esquerda devem vir entre aspas. Palavras como yes e no também podem ser lidas como verdadeiro ou falso por alguns interpretadores, então é mais seguro colocá-las entre aspas quando forem texto. ## Exemplos de YAML na especificação OpenAPI - Uma software house baixa o arquivo openapi.yaml de uma API fiscal e o abre no Swagger UI para conhecer os endpoints de emissão de NFS-e antes de começar a programar. - Uma equipe de desenvolvimento usa o YAML da especificação para gerar automaticamente um cliente em Java, evitando escrever à mão as classes que representam emitente, tomador e itens da nota. - Ao revisar o schema de um item da NF-e, um desenvolvedor percebe que o campo NCM estava declarado como número e o corrige para string, preservando códigos que começam com zero. - Um time de produto adiciona comentários com # no arquivo YAML para explicar quando o campo de retenção de ISSQN deve ser preenchido, facilitando o entendimento de quem integra. ## Perguntas frequentes ### Preciso saber YAML para usar uma API fiscal? Não. O arquivo YAML serve para descrever a API; as requisições em si normalmente são feitas em JSON. Mas saber lê-lo ajuda a entender campos obrigatórios, formatos aceitos e respostas de erro sem depender apenas da documentação em texto. ### O arquivo OpenAPI pode estar em .yml ou .yaml? Sim. As duas extensões são aceitas e representam o mesmo formato. A escolha é apenas de convenção da equipe; as ferramentas de OpenAPI reconhecem ambas. ### Posso converter um OpenAPI em YAML para JSON? Sim. Os dois formatos são equivalentes na OpenAPI, e editores e ferramentas de linha de comando fazem a conversão automaticamente. A única perda costuma ser a dos comentários, que o JSON não suporta. ## Termos relacionados - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Swagger UI](https://conota.dev/glossario/swagger-ui.md) - [JSON](https://conota.dev/glossario/json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Schema de validação](https://conota.dev/glossario/schema-de-validacao.md) --- Fonte: [YAML na especificação OpenAPI](https://conota.dev/glossario/yaml-na-especificacao-openapi/) · Atualizado em 2026-10-22 --- # YAML null > YAML null é o valor que representa a ausência de dado em arquivos YAML, um formato de texto muito usado em configurações e em especificações de APIs. Pode ser escrito como null, Null, NULL, til (~) ou deixando o campo sem valor, e equivale ao null do JSON e ao None ou nil das linguagens de programação. **Também conhecido como:** Nulo em YAML, Valor nulo YAML, ~ (til) em YAML, YAML null **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que significa null em um arquivo YAML? YAML é um formato de texto para organizar informações em pares de chave e valor, usando recuos em vez de chaves e colchetes. Ele é comum em arquivos de configuração de sistemas, em pipelines de implantação e em documentos que descrevem APIs. Null é a forma de dizer que um campo existe, mas não tem valor. Não é zero, não é texto vazio e não é falso: é a indicação explícita de que ali não há informação. Por exemplo, um campo de complemento de endereço pode ficar null quando o cliente mora em uma casa sem número de apartamento. ## Como escrever null em YAML? Na especificação mais usada do YAML, são reconhecidas como null as palavras null, Null e NULL, o símbolo til (~) e também a chave sem nenhum valor depois dos dois-pontos. Assim, as linhas complemento: null, complemento: ~ e complemento: produzem o mesmo resultado ao serem lidas por um sistema. Um cuidado importante: se a palavra estiver entre aspas, como complemento: "null", ela deixa de ser null e passa a ser um texto com as letras n, u, l, l. Esse detalhe causa muitos erros difíceis de perceber. ## Qual a diferença entre null, texto vazio e campo ausente? São três situações distintas. Com null, o campo aparece, mas sem valor. Com texto vazio (duas aspas sem nada dentro), o campo tem um valor, que é um texto de tamanho zero. Com o campo ausente, a chave simplesmente não está no arquivo. Muitos sistemas tratam essas situações de forma diferente. Uma API pode aceitar o campo ausente, mas recusar o texto vazio, ou interpretar null como uma ordem para apagar um valor já salvo. Por isso, vale conferir na documentação qual comportamento é esperado em cada campo. ## Por que o YAML null importa na integração com uma API fiscal? APIs fiscais costumam receber dados em JSON, mas muitas equipes guardam configurações, modelos de requisição ou a própria descrição da API em YAML. Quando esse conteúdo é convertido, o null do YAML vira o null do JSON, e é isso que chega ao emissor. Nos documentos fiscais eletrônicos, como NF-e, NFC-e e CT-e, o XML final segue um esquema rígido. Em geral, campos opcionais sem informação devem ser omitidos, e não enviados vazios, pois tags vazias costumam gerar falha de validação do esquema e rejeição. Entender como seu sistema trata o null ajuda a evitar que um campo sem valor vire uma tag vazia ou um texto "null" dentro da nota. ## Quais erros mais comuns envolvem YAML null? Os mais frequentes são: colocar null entre aspas e enviar a palavra como texto; esquecer o valor de uma chave e, sem querer, gerar null; e confundir null com zero em campos numéricos, como valor de desconto ou alíquota. No caso de valores tributários, zero e ausência de valor podem ter significados fiscais diferentes. Uma boa prática é validar os dados com um esquema, como o JSON Schema, antes de enviá-los à API, definindo quais campos aceitam null e quais são obrigatórios. ## Exemplos de YAML null - Em um arquivo de configuração de um ERP, a linha certificado_senha_secundaria: ~ indica que não existe uma segunda senha cadastrada para aquela empresa emissora. - Na descrição de uma API de emissão de NF-e escrita em YAML, um campo de complemento de endereço do destinatário é marcado como podendo ser null, sinalizando que ele é opcional. - Um desenvolvedor escreve inscricao_municipal: "null" entre aspas em um modelo de NFS-e; o sistema envia a palavra null como texto e o emissor retorna erro de validação. - Um modelo de requisição em YAML define valor_desconto: null; ao converter para JSON, o campo chega como null e o sistema emissor entende que não houve desconto informado, em vez de desconto igual a zero. ## Perguntas frequentes ### YAML null é o mesmo que JSON null? Têm o mesmo significado: ausência de valor. Ao converter YAML para JSON, null, ~ ou um campo sem valor se transformam em null no JSON. A diferença está só na escrita, já que o JSON aceita apenas a palavra null em minúsculas. ### Deixar o campo vazio em YAML é igual a escrever null? Sim. Uma chave seguida de dois-pontos e nada depois é interpretada como null. Isso é prático, mas pode gerar null por descuido, quando a pessoa apenas esqueceu de preencher o valor. ### Posso enviar null em qualquer campo de uma API fiscal? Não. Campos obrigatórios, como CNPJ do emitente ou valores dos itens, precisam de valor. Consulte a documentação da API para saber quais campos aceitam null e quais devem ser omitidos quando não houver informação. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) --- Fonte: [YAML null](https://conota.dev/glossario/yaml-null/) · Atualizado em 2026-10-22 --- # YAML quoted string > YAML quoted string é um valor de texto escrito entre aspas simples ou duplas em um arquivo YAML. As aspas garantem que o conteúdo seja lido literalmente como texto, evitando que números, datas, palavras como yes ou no e caracteres especiais sejam interpretados de outra forma. Isso é importante em configurações de integrações, chaves e identificadores. **Também conhecido como:** String entre aspas em YAML, Escalar entre aspas, Quoted scalar, Texto entre aspas no YAML, YAML quoted string **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é uma YAML quoted string? YAML é um formato de texto usado para escrever configurações de forma legível, com pares de chave e valor organizados por indentação. Ele aparece em arquivos de configuração de sistemas, pipelines de implantação, especificações de APIs e ferramentas de infraestrutura. No YAML, um valor pode ser escrito sem aspas (chamado de escalar simples) ou entre aspas. Quando o valor está entre aspas simples ou duplas, ele é uma quoted string: o leitor do arquivo entende que aquilo é texto, e não um número, um valor lógico ou um valor nulo. ## Por que usar aspas em valores YAML? Sem aspas, o YAML tenta adivinhar o tipo do valor. A palavra true vira verdadeiro, 123 vira número, null vira vazio. Em versões mais antigas da especificação, até palavras como yes, no, on e off eram convertidas em verdadeiro ou falso. Um código de país como NO, por exemplo, podia virar falso. Números com zeros à esquerda também são um risco: dependendo do leitor, o valor pode perder os zeros ou ser interpretado como número em base octal. Em dados fiscais isso é crítico, porque um CNPJ, um CEP, um código de município ou uma série de nota com zero inicial deixaria de estar correto. Com aspas, o valor é preservado exatamente como foi digitado. ## Qual a diferença entre aspas simples e aspas duplas no YAML? Nas aspas simples, o texto é lido de forma praticamente literal. A barra invertida não tem significado especial, e a única regra é que, para escrever uma aspa simples dentro do texto, é preciso repeti-la, como em 'Nota d''água'. Nas aspas duplas, é possível usar sequências de escape com barra invertida, como n para quebra de linha, t para tabulação, " para aspas duplas e \ para a própria barra. Elas são úteis quando o texto precisa conter caracteres especiais. A desvantagem é que uma barra invertida esquecida pode alterar o valor sem que se perceba. ## Quando as aspas são obrigatórias? As aspas são necessárias quando o valor começa com caracteres que têm significado no YAML, como dois-pontos seguidos de espaço, cerquilha, colchetes, chaves, asterisco, e comercial ou arroba. Também são recomendadas quando o texto contém dois-pontos no meio, como em URLs com porta ou horários. Na prática, uma boa regra é colocar entre aspas qualquer identificador que pareça número mas não seja usado em cálculos: CNPJ, CPF, inscrição estadual, CFOP, código de serviço, chave de acesso e tokens de autenticação. ## Como isso aparece em uma integração fiscal? Sistemas que emitem documentos fiscais por API costumam guardar parâmetros em arquivos YAML: endereço do endpoint, ambiente de homologação ou produção, CNPJ do emitente, série da nota e referências a chaves de API. Se algum desses valores for interpretado com o tipo errado, a requisição pode sair com dados incorretos e ser rejeitada. Para textos longos com várias linhas, como um certificado em formato PEM, o YAML oferece os blocos literais com o símbolo |, que mantêm as quebras de linha sem precisar de escapes. Já segredos como chaves de API não devem ficar escritos diretamente no arquivo; o ideal é referenciá-los a partir de um cofre ou de variáveis de ambiente. ## Exemplos de YAML quoted string - Configuração de emitente: cnpj: "01234567000189" mantém o zero inicial; sem aspas, o leitor poderia converter o valor em número e perder o zero. - Escolha de ambiente: ambiente: "homologacao" e serie: "001", garantindo que a série seja enviada como texto com três dígitos para a API fiscal. - Código de município em configuração de NFS-e: codigo_municipio: "3550308", evitando que o valor seja tratado como número em validações que esperam texto. - Mensagem com caracteres especiais: observacao: "Pedido #4521: entrega parcial", em que as aspas impedem que a cerquilha e os dois-pontos sejam interpretados pelo YAML. ## Perguntas frequentes ### Todo texto em YAML precisa estar entre aspas? Não. Textos comuns funcionam sem aspas. Elas são necessárias quando o valor pode ser confundido com número, booleano, nulo ou data, ou quando contém caracteres especiais do YAML, como dois-pontos seguidos de espaço ou cerquilha. ### Devo preferir aspas simples ou duplas? Aspas simples são mais seguras para textos literais, como identificadores e senhas, porque não interpretam barras invertidas. Aspas duplas são indicadas quando o texto precisa de escapes, como quebras de linha ou caracteres Unicode. ### Qual a relação entre YAML e JSON? YAML 1.2 foi projetado para ser compatível com JSON, então quase todo JSON válido também é YAML válido. No JSON, porém, todo texto precisa estar entre aspas duplas, enquanto no YAML as aspas são opcionais em muitos casos. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [API Key](https://conota.dev/glossario/api-key.md) - [Endpoint de API](https://conota.dev/glossario/endpoint-de-api.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) --- Fonte: [YAML quoted string](https://conota.dev/glossario/yaml-quoted-string/) · Atualizado em 2026-10-22 --- # YAML scalar > YAML scalar é o valor mais simples de um arquivo YAML: um dado único, como texto, número, booleano, data ou nulo, que não contém outros elementos dentro de si. Em integrações fiscais, escalares aparecem em arquivos de configuração e especificações de API, guardando informações como ambiente, série, CNPJ ou URL de endpoint. **Também conhecido como:** Escalar YAML, Valor escalar, Scalar YAML, Nó escalar, YAML scalar **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## O que é um scalar no YAML? YAML é um formato de texto usado para escrever configurações e descrições de dados de forma legível para pessoas. Ele trabalha com três tipos básicos de estrutura: mapas (pares de chave e valor), listas (sequências de itens) e escalares. O scalar, ou escalar, é o valor final, aquele que não se divide em partes menores. Na linha ambiente: homologacao, a palavra homologacao é um escalar. Na linha serie: 1, o número 1 também é. Mapas e listas servem para organizar os escalares, que são onde a informação de fato fica guardada. ## Quais tipos de valores um scalar pode representar? Os escalares mais comuns são textos (strings), números inteiros, números decimais, booleanos (true ou false), valores nulos (null ou til) e, em alguns leitores de YAML, datas. O leitor do arquivo tenta descobrir o tipo automaticamente olhando para o valor escrito. Essa detecção automática é prática, mas pode surpreender. Um valor como 0012 pode ser lido como número e perder os zeros à esquerda, e palavras como yes, no, on e off podem virar booleanos em algumas versões e bibliotecas. Para garantir que o valor seja tratado como texto, basta colocá-lo entre aspas. ## Quais são os estilos de escrita de um scalar? Existem escalares sem aspas (plain), com aspas simples e com aspas duplas. As aspas duplas permitem sequências especiais, como n para quebra de linha, enquanto as aspas simples tratam quase tudo de forma literal. Para textos longos, há os estilos de bloco. O símbolo | (literal) preserva as quebras de linha exatamente como foram escritas, útil para guardar trechos de certificado em formato PEM ou mensagens com várias linhas. O símbolo > (dobrado) junta as linhas em um único parágrafo, útil para descrições extensas. ## Por que o YAML scalar importa em integrações fiscais? Muitas equipes que integram ERPs, plataformas de venda e marketplaces a uma API fiscal usam YAML para guardar configurações: ambiente de homologação ou produção, série da NF-e, código do município, tempo de timeout e endereço do endpoint. Também é comum que especificações OpenAPI de APIs REST sejam escritas em YAML. Em dados fiscais, o tipo do escalar faz diferença. CNPJ, inscrição estadual, CEP, código de município e NCM devem ser tratados como texto, porque zeros à esquerda fazem parte do valor. Se o YAML transformar 01234567000189 em número, o dado chega errado ao payload e pode gerar um erro de validação ou uma rejeição fiscal. ## Qual a diferença entre um scalar no YAML e um valor no JSON? A ideia é a mesma: o escalar do YAML corresponde aos valores primitivos do JSON, como string, número, booleano e null. A diferença está na escrita. No JSON, textos sempre ficam entre aspas, então o tipo é explícito. No YAML, as aspas são opcionais, e o tipo é deduzido pelo leitor. Por isso, ao converter configurações YAML em JSON para enviar a uma API, vale conferir se cada escalar virou o tipo esperado pelo JSON Schema da requisição. ## Exemplos de YAML scalar - Arquivo de configuração de um ERP com a linha ambiente: "homologacao", em que o escalar define se as notas serão enviadas ao ambiente de testes ou ao de produção. - Campo cnpj_emitente: "01234567000189" escrito entre aspas para que o escalar seja lido como texto e preserve o zero inicial. - Especificação OpenAPI em YAML de uma API fiscal, com escalares como type: string e format: date-time descrevendo os campos do payload de emissão. - Chave de configuração com o estilo de bloco | para guardar um texto de várias linhas, como uma observação padrão a ser incluída nas informações complementares da nota. ## Perguntas frequentes ### Preciso colocar aspas em todo scalar YAML? Não é obrigatório, mas é recomendável em valores que devem ser texto e podem ser confundidos com outros tipos, como CNPJ, CEP, códigos com zeros à esquerda, versões como 1.10 e palavras como yes, no, on e off. ### Um scalar pode conter várias linhas? Sim. Com os indicadores de bloco | e >, um único escalar pode ocupar várias linhas. O | preserva as quebras de linha, e o > junta as linhas em um texto contínuo. ### O que acontece se um scalar for lido com o tipo errado? O sistema pode enviar dados incorretos. Um código que perde zeros à esquerda, por exemplo, pode causar erro de validação na API ou rejeição do documento fiscal pelo órgão autorizador. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [OpenAPI](https://conota.dev/glossario/openapi.md) - [Payload de emissão fiscal](https://conota.dev/glossario/payload-de-emissao-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) --- Fonte: [YAML scalar](https://conota.dev/glossario/yaml-scalar/) · Atualizado em 2026-10-22 --- # YAML sequence > YAML sequence é a estrutura do formato YAML usada para representar uma lista ordenada de itens. Cada elemento costuma aparecer em uma linha própria, iniciada por hífen e espaço, ou entre colchetes separados por vírgulas. Equivale a um array em JSON e aparece em arquivos de configuração, especificações OpenAPI e manifestos Kubernetes. **Também conhecido como:** Sequência YAML, Lista YAML, Array YAML, Sequence em YAML, YAML sequence **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### Uma YAML sequence pode misturar tipos de itens diferentes? Sim. Uma mesma lista pode conter textos, números, objetos e outras listas. Porém, em especificações de API e configurações, o recomendado é manter itens do mesmo tipo para facilitar a validação e evitar erros na leitura pelos sistemas. ### A ordem dos itens em uma YAML sequence importa? Sim. A sequence preserva a ordem em que os itens foram escritos, e o programa que lê o arquivo recebe a lista nessa mesma ordem. Isso é útil, por exemplo, para definir a sequência de etapas de um processo. ### Preciso saber YAML para emitir notas fiscais por API? Normalmente não. Os payloads de emissão costumam ser enviados em JSON. O YAML aparece mais em documentação OpenAPI e em arquivos de configuração e deploy, então ajuda quem cuida da infraestrutura ou lê a especificação da API. ### Posso usar tabulação para indentar uma sequence? Não. A especificação YAML não aceita tabulações na indentação. Use espaços, mantendo o mesmo recuo para todos os itens da mesma lista. Editores de código costumam converter a tecla Tab em espaços automaticamente. ## Termos relacionados - [OpenAPI](https://conota.dev/glossario/openapi.md) - [JSON](https://conota.dev/glossario/json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Schema de validação](https://conota.dev/glossario/schema-de-validacao.md) - [Kubernetes na infraestrutura de APIs](https://conota.dev/glossario/kubernetes-na-infraestrutura-de-apis.md) - [Swagger UI](https://conota.dev/glossario/swagger-ui.md) --- Fonte: [YAML sequence](https://conota.dev/glossario/yaml-sequence/) · Atualizado em 2026-10-22 --- # YAML tag > YAML tag é um marcador iniciado pelo símbolo de exclamação que, em arquivos no formato YAML, indica explicitamente o tipo de um valor, como texto, número inteiro, data ou dado binário. Ela evita que o programa leitor interprete o conteúdo de forma errada, algo importante em configurações e especificações de integrações com APIs fiscais. **Também conhecido como:** Tag YAML, Marcador de tipo YAML, Etiqueta de tipo YAML, YAML tag **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** Y ## 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. ## Perguntas frequentes ### Toda informação em YAML precisa de tag? Não. Na maioria dos casos o leitor identifica o tipo corretamente sozinho. A tag é útil quando há risco de interpretação errada, como em códigos com zeros à esquerda ou valores que parecem booleanos. ### A API do emissor fiscal recebe YAML? Geralmente as APIs fiscais recebem dados em JSON. O YAML costuma aparecer em arquivos de configuração, especificações de API e scripts do sistema integrador, que depois convertem os dados para o formato exigido pela API. ### YAML tag tem relação com tag XML? Apenas no nome. A tag XML delimita um elemento do documento, como no XML da NF-e. A tag YAML indica o tipo de um valor dentro de um arquivo YAML. ## Termos relacionados - [JSON](https://conota.dev/glossario/json.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [API REST para emissão fiscal](https://conota.dev/glossario/api-rest-para-emissao-fiscal.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [YAML tag](https://conota.dev/glossario/yaml-tag/) · Atualizado em 2026-10-22