YAML の細かい仕様の話

2023-05-01T01:32:11+09:00

グワーッ！YAML 1.2 って、 yes,no,on,off 系が Boolean リテラルではなくなる破壊的変更あるん!?Docker Compose v2.17.0 で内部パーサが go-yaml/yaml.v3 に更新され、真偽値を yes, no で書いてた compose.yml ファイルが軒並み must be a boolean エラー出まくってて死。https://t.co/PVpdIWFVgA
— ながいの as a サービス (@longer_n) April 12, 2023

趣味アカウントのほうでバズった… ってほどでは無いけど、割と反響があったので、 YAML に関する話をいくつか。

YAML 1.2 では Boolean として扱うのは true, false だけ

https://yaml.org/type/bool.html

YAML 1.1 では以下の文字が Boolean として認識されるのが一般的だ。
y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF

厳密には、 !!bool タグを使って Boolean 型を表現する場合の表記方法だが、基本的には多くのパーサーではタグを書かなくても Boolean 型として扱われる。

https://yaml.org/spec/1.2.0/#id2602744

しかし YAML 1.2 以降ではこれが、 true, false のみが Boolean として認識されるという、だいぶデカい破壊的変更が入っている。

ここで、 1.2.0 の主たる更新点を見てみると…
https://yaml.org/spec/1.2.2/ext/changes/#changes-in-version-12-revision-120-2009-07-21

Changes in version 1.2 (revision 1.2.0) (2009-07-21)

[...]

Only true and false strings are parsed as booleans (including True and TRUE); y, yes, on, and their negative counterparts are parsed as strings.

Underlines _ cannot be used within numerical values.

Octal values need a 0o prefix; e.g. 010 is now parsed with the value 10 rather than 8.

The binary and sexagesimal integer formats have been dropped.

The !!pairs, !!omap, !!set, !!timestamp and !!binary types have been dropped.

The merge

参考日本語訳:

true と false の文字列のみがブーリアン（TrueとTRUEを含む）として解析される。 y, yes, on およびそれらの否定語は文字列として解析される。

アンダーライン _ は、数値の中では使用できません。

8進数の値には0oのプレフィックスが必要です。例えば010は8ではなく10という値で解析されるようになりました。

二進法と十進法の整数形式は廃止されました。

ペア、オマップ、セット、タイムスタンプ、バイナリ型は削除されました。

merge

うーん、現代のセマンティックバージョニングだったら、絶対にマイナー場ジョンアップじゃダメなヤツ。

こういった仕様のため、 yes, no と書いた際にどう扱われるかは、パーサーの実装による。

例えば、 PyYAML などは Boolean リテラルとして扱われるが、 go-yaml/yaml.v3 では文字列として扱われる。

内部パーサーの更新でこの解釈が変わってしまったために発生したのが、冒頭の問題だ。

Ansible などでは、真偽値を yes, no と書く慣習があるせいで、もうめちゃくちゃあっちこっちで yes, no って書いてるわ…

なお、冒頭の Docker Compose については、 Docker Compose version v2.17.3 で yes 等を書いてもエラーにせずワーニングだけ出すように修正された。
[BUG] Error "must be a boolean" with yes scalar in Docker Compose v2.17.0 · Issue #10465 · docker/compose

">" は全ての改行をスペースに置き換えるわけではない

ブロックスタイルの文字列表記で、 ">" インジゲータを置くと、次の行から途中の改行が半角スペースに置き換えられると説明されがちだ。

foo: >
  trimmed
  line

しかし、半角スペースに置き換えられる条件はもう少し複雑だ。

https://yaml.org/spec/1.2.2/#line-folding

この Line Folding と言うのがこれに当たるのだが、これは長い行を折りたたんで読みやすくするための機能だ。

折りたたまれた部分（改行）が半角スペース (0x20) に変換されるものだが、

複数の改行が続く場合は最初の改行が破棄され、残りは保持される
先頭の空白を含むテキスト行（つまりインデントされた行）は、行の折り返しは適用されない。

という仕様がある。

このため、以下のように動作する。

YAML 入力:

foo: >
  trimmed
  line
  breaking

  but blank line and
    nested
    line
  are are retained.

JSON 出力:

{ "foo": "trimmed line breaking\nbut blank line and\n  nested\n  line\nare are retained.\n" }

つまり、「改行を消す」というよりは、「次の行のインデントの高さがブロックの先頭と同じ場合のみ、行の折りたたみと見なして改行を削除する」という動作となる。

マージキー (<<) によるマージは 1回しか記述できない。

複数のマップをマージしたい場合は、シーケンス（配列）によって指定する。

https://yaml.org/type/merge.html

YAML 入力:

-
  - &ANCHER1 { '0': 0, a: 0, b: 0 }
  - &ANCHER2 { b: 99, c: 99 }
  - &ANCHER3 { c: 255, d: 255 }
#- # Eror
#  '0': 1
#  << : *ANCHER1
#  << : *ANCHER2
#  << : *ANCHER3
#  a: 1
- # Single map
  b: 1
  << : *ANCHER2
- # Override multiple maps
  '0': 1
  << : 
    - *ANCHER1
    - *ANCHER2
    - *ANCHER3
  a: 1

JSON 出力:

[
  [
    { "a": 0, "b": 0 },
    { "b": 99, "c": 99 },
    { "c": 255, "d": 255 }
  ],
  { "b": 1, "c": 99 },
  { "0": 1, "a": 1, "b": 0, "c": 99, "d": 255 }
]

シーケンスで複数のマップを指定した場合で、キーが重複している物は、シーケンス内では順序が前のものが常に優先される。
一方で、マージキーで指定したモノよりは、マージ先のものが優先となる。

ただ、パーサーによってはマージキー (<<) を複数書く誤った書き方に対応しているモノがあり、
実際、 Docker Compose v2.17.0 で、内部パーサーが go-yaml/v3 に切り替わったときに、誤った書き方が対応から未対応に変わって、以下のようなエラーが出てハマった。

mapping key "<<" already defined at line nnn

[[BUG]using multiple yaml alias not working. mapping key "

もちろんこれは、マージキーを複数書く方が悪いので、 YAML の方を直す必要がある。

例: https://go.dev/play/p/jos7jc38loK
-->

「YAML」の記事 - Crieit

YAML の細かい仕様の話

YAML 1.2 では Boolean として扱うのは true, false だけ

Changes in version 1.2 (revision 1.2.0) (2009-07-21)

">" は全ての改行をスペースに置き換えるわけではない

マージキー (<<) によるマージは 1回 しか記述できない。

マージキー (<<) によるマージは 1回しか記述できない。