引用符を外すと値が変わる場所
YAMLは引用符のない値の型を自分で決めます。事故はここで起きます。
version: 1.10は数値として読まれ1.1になります。末尾の0が消えてバージョンの意味が変わってしまいます。zip: 01234も数値になり、先頭の0が落ちて1234です。郵便番号や社員番号、電話番号のように先頭の0が意味を持つ値は"01234"と引用符で囲んでください。
12:30のような時刻表記やno、yes、onは、このツールでは文字列のまま残ります。ただしPyYAMLやRubyのように古い規格に従うパーサーではnoが偽として読まれます。国コードのNOがfalseになってしまう話が有名です。複数のツールを通る設定なら、こうした語も引用符で囲んでおくと安全です。
インデントの決まり
インデントは半角スペースだけです。タブは構文エラーになります。エディタがタブを入れる設定なら、YAMLファイルではスペースに切り替えてください。
同じ階層の項目は桁をきっちり揃える必要があります。1つでもずれるとその場で失敗します。このツールは止まった行と桁をそのまま知らせます。
アンカーとマージキー
&名前でまとまりに名前を付け、*名前で呼び出します。そこに<<:を足すと、そのまとまりを別のマップに流し込めます。
defaults: &d
retry: 2
image: node
job:
<<: *d
script: testこのツールはマージキーを展開するので、jobの中にretryとimageが入ったJSONが出ます。展開しないと"<<"というキーがそのまま残り、後の工程で使えません。GitLab CIやDocker Composeの設定でよく見かける書き方です。
JSONにすると失われるもの
コメントが消えます。JSONにはコメントの構文がありません。設定ファイルを変換して元のファイルに上書きすると、書き残しておいた説明がすべて失われます。元は残しておいてください。
複数の文書も入りません。---で区切られた文書が複数あると、このツールはエラーにします。黙って最初の1つだけを出すと、残りが消えたことに気づけないからです。Kubernetesのマニフェストのように複数の文書を含むファイルは、1つずつ分けて入れてください。
日付は文字列になります。YAMLは日付を型として認識しますが、JSONに対応する型はありません。
逆向きに変換するとき
JSONをYAMLにすると引用符の多くが外れて読みやすくなります。ただし先頭が0の文字列やtrueに見える文字列には引用符が残ります。外すと意味が変わってしまうためで、残っているのが正しい動きです。