O problema da Noruega no YAML

O que é o problema da Noruega?

Escreva country: NO num arquivo YAML e um monte de analisadores vai devolver o booleano false em vez da string “NO”. O código de país da Noruega é uma grafia de false no YAML 1.1, junto com outras quinze palavras comuns, e nada no arquivo sinaliza isso: o valor chega como booleano e algo quebra bem mais adiante.

Isso acontece porque há duas especificações de YAML em uso diário. O YAML 1.1, de 2005, aceita vinte e duas grafias de booleano: y, Y, yes, Yes, YES, n, N, no, No, NO, true, True, TRUE, false, False, FALSE, on, On, ON, off, Off e OFF. O YAML 1.2 reduziu para seis — true, True, TRUE, false, False, FALSE —, então as outras dezesseis viraram texto comum. As duas versões são amplamente implementadas, ou seja, o mesmo arquivo significa de fato duas coisas.

Os booleanos são o caso famoso, não o único. No YAML 1.1 um valor como 12:30 é um número em base sessenta e vira 750; um zero à frente significa octal, então 0755 é 493; e sublinhados são separadores de dígitos, então 1_000 é mil. No YAML 1.2 os três são strings ou decimais normais. Esta página confere um arquivo procurando essa família inteira de uma vez.

Como usar

1. Cole seu YAML. Um arquivo inteiro ou só o trecho que preocupa. Nada é enviado — a conferência roda na própria página.
2. Leia a tabela. Cada valor simples cujo sentido depende da versão, com o que o YAML 1.1 faz dele, o que o 1.2 faz, e qual regra é a responsável.
3. Ponha aspas no que for apontado. Um escalar entre aspas é string em toda versão e em todo analisador. Colocar aspas é a correção inteira, e a tabela vai esvaziando conforme você faz isso.

Qual analisador eu estou usando, afinal?

É dessa pergunta que o problema da Noruega realmente depende, e a resposta raramente é visível de fora. O PyYAML — de longe a biblioteca YAML mais usada em Python, e portanto o que está por baixo de boa parte da tooling de infraestrutura — implementa o YAML 1.1, então lê NO como false até hoje. Em JavaScript, o js-yaml resolve o esquema core do YAML 1.2, então o mesmo arquivo devolve a string. As bibliotecas de Go, Ruby e Java variam conforme a versão e o esquema com que foram configuradas.

A consequência prática é que um arquivo pode passar em todos os testes numa máquina e mudar de sentido em outra, sem um erro sequer em lugar nenhum. Uma configuração escrita e validada numa toolchain JavaScript e depois lida por um serviço em Python é exatamente o formato dessa falha — e códigos de país, flags escritas como on e off e horários escritos como 12:30 são comuns o bastante para encontrá-la.

É também por isso que a correção é colocar aspas, e não escolher um lado. Você não controla qual analisador vai ler o seu arquivo lá na frente, e uma string entre aspas significa a mesma coisa para todos eles.

Limites honestos

Esta página lê os valores linha a linha em vez de analisar YAML de verdade, e é deliberadamente restrita nisso: só olha linhas de chave e valor e itens de lista simples, pula tudo o que já está entre aspas, e pula inteiro qualquer escalar de bloco introduzido por barra vertical ou sinal de maior, junto com todo o corpo indentado. Esse último ponto importa — um script de shell dentro de um escalar de bloco pode ter linhas que parecem YAML exatamente, e apontá-las seria falso positivo, não achado.

Essa restrição custa alguma coisa. Coleções em linha, arquivos com vários documentos, âncoras e chaves de mesclagem não são analisados, então um valor escondido em um desses não aparece. O leitor prefere não dizer nada a dizer algo errado.

As regras do YAML 1.1 são transcritas das próprias páginas de tipos do yaml.org, que publicam as expressões regulares de resolução, e a transcrição é conferida contra essas páginas em vez de aceita de olhos fechados. As respostas do 1.2 são conferidas com o js-yaml, a biblioteca que este site já usa em outras páginas. Nada disso faz desta página um substituto para rodar o seu analisador real no seu arquivo real.

Por fim, um valor aparecer na lista não significa que a sua configuração esteja quebrada. Se tudo que lê o arquivo está no YAML 1.2, NO já é string e não há problema algum. A tabela diz onde o arquivo depende dessa suposição, não que a suposição seja falsa agora.

Por que é grátis?

A conferência são algumas centenas de linhas de comparação de padrões rodando no seu navegador. Não há servidor envolvido, então não há o que cobrar nem cadastro a fazer — e isso importa aqui, porque um arquivo de configuração costuma citar hosts internos, buckets e serviços.

Nada é enviado e nada é guardado. Recarregue a página e ela terá esquecido o arquivo.