# 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