YAML boolean

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.