YAMLファイルとは

YAML はプレーンテキスト形式です。どのエディターでも開けます。 プログラム間のデータ受け渡しと編集のために使われます。

拡張子は .yaml、正式名称は YAML Ain't Markup Language です。ただしどちらも、そのファイルが中に何を持てるかほどには多くを語りません。このページの残りは、その中身についての話です。

2001 年までさかのぼります。 仕様は YAML 1.2 です。

古さが役に立つのは、ごく実務的な理由からです。形式が古いほど、それを覚える時間が多くのプログラムに与えられてきたということだからです。

仕様書がそのまま公開されているので、中身を推し量るのではなく文書を読んで実装できます。この形式が数多くのプログラムに載っているのはそのためであり、20 年前に書かれたファイルが今も開けるのもそのためです。ただし「仕様が公開されている」ことと「使用料が要らない」ことは別の話です。中でコーデックを包んでいる形式では、特許のライセンスは仕様書が答えていない別の問題として残ります。

YAML ファイルは中身をそのまま保存します。保存し直しても何も変わらないので、開いて、直して、また保存する——それを何度繰り返しても劣化は積み上がりません。これが、渡すための形式ではなく作業のための形式である理由です。

YAML ファイルにはコメントを書く方法があります。人が面倒を見るファイルと、プログラムが書き出すファイルを分けるのは、まさにこの一点です。コメントを持てない形式へ変換すると真っ先に消え、しかも誰も警告してくれません。

Visual Studio Codeとyqが読めますし、同じ種類のプログラムならたいてい読めます。

ファイルが開かないとき、形式が悪いことはめったにありません。たいていはプログラムのほうが形式より古いのです。もっと古い形式に変換してしまうのが確実な逃げ道で、このサイトの残りの部分はそのためにあります。

これを読めるブラウザーはありません。

これを変換するいちばんよくある理由がこれです。形式が悪いのではありません。ファイルを見せたい場所が、それを読めないというだけのことです。

YAML は、開いて手を入れるために作られています。作業が続いているあいだはこの形式でファイルを持ち、完成したものが必要になるたびに、ここから書き出してください。

YAML を自分で選ぶ人はほとんどいません。渡されるものです。Kubernetes のマニフェスト、GitHub Actions や GitLab CI のパイプライン、Ansible の playbook、Docker Compose、OpenAPI の仕様、静的サイトのフロントマター。これらはみなこれに落ち着いていて、その周辺のエコシステムは、この形式が誰かに選び直される余地がないほど巨大です。

これが、この形式について役立つページの形を決めています。問題は YAML を使うかどうかではなく、めったにありません。どうすればこの形式特有の壊れ方を避けられるか、です。よく使われる設定形式の中で、これほど静かに失敗するものは他にありません。

括弧も閉じる印もありません。行がどれだけ深くインデントされているかが、それが何に属するかを決めるため、間違った場所にあるスペース一つが文書の意味を変えてしまいます。しかもそれは、意図とは違うだけの、今も有効な文書であることがよくあります。

二つのルールがほとんどの問題を防ぎます。タブは絶対に使わないでください。仕様がそれを禁じていて、タブを挿入するエディターはたいてい、その原因を明示しないまま解析エラーを出します。そしてインデントは一貫させ、慣習として一段階につき二スペースにしてください。ファイル内で幅が混在するのは仕様上は合法ですが、構造がひと目では読み取れなくなります。

YAML は裸の値が何であるかを推測し、その推測は実際の障害を引き起こしてきました。有名なのはノルウェー問題です。YAML 1.1 では、引用符なしの no は真偽値の false として読まれるため、国コードのリストの NO が false になります。on、off、y、n でも同じことが起きます。

バージョン番号も同じ問題を抱えています。1.20 は浮動小数点数の 1.2 になり、末尾のゼロが消えます。時刻も問題です。22:30 は文字列ではなく六十進数として読まれることがあります。そして 0755 のような値は八進数として読まれることがあります。

対処は知識というより習慣です。テキストとして扱いたいものはすべて引用符で囲んでください。バージョン番号、国コード、識別子、時刻、先頭にゼロが付く値です。YAML 1.2 はこれらの多くを修正しましたが、今も多くのパーサーが 1.1 を実装しているため、あなたを守るのは仕様ではなくこの習慣です。

YAML はブロックを一度定義して再利用できます。アンカーがそれに印を付け、エイリアスがそれを参照し、マージキーは共有されたブロックを複数の場所に折り込みます。CI パイプラインが同じ六行をすべてのジョブで繰り返さずに済むのはこの仕組みのおかげです。

これは本当に便利ですが、この構文を見たことのない人にとっては、ここから読みにくくなる境界線でもあります。実務上の注意点が二つあります。エイリアスはコピーではなく参照なので、共有されているものは本当に共有されています。そして YAML を読み込む一部のツールはアンカーをまったく実装していないか、思わぬ形で展開します。それを土台に大きな設定を組む前に確認してください。

縦棒で書かれたブロックスカラーは改行を保ちます。スクリプトや証明書、段落のあるメッセージに向いています。大なり記号で書くと、行は一つに折り畳まれます。ファイル内で読みやすさのために折り返された長い文に向いています。

どちらも末尾の改行を制御する接尾辞を取れます。マイナスは取り除き、プラスはすべての末尾の改行を保ちます。値がキーやトークン、スクリプトである場合、これは見た目以上に重要です。予期しない末尾の改行は、証明書が拒否されたり、コマンドがパイプラインと手元の環境で違う振る舞いをしたりする典型的な原因です。

単独の行にある三つのハイフンは新しい文書の始まりを示すため、一つのファイルがその連続を保持できます。Kubernetes はこれを頻繁に使い、一つのファイルにデプロイメント、サービス、コンフィグマップをまとめます。それを読み込むどのツールもこれを想定しています。

これは「このファイルを解析する」という言葉の意味を変えるため、知っておく価値があります。一つの文書だけを読み込むパーサーは、最初の区切りより後をすべて静かに無視してしまい、エラーもなく設定の半分が消える原因になります。対応する関数は、たいてい一つではなくすべての文書を読み込むための名前が別に用意されています。

すべての JSON 文書はすでに有効な YAML です。YAML 1.2 が JSON の上位集合として定義されているためです。そのため JSON を YAML に変換するのはほぼ見た目だけの単純な作業で、結果は同じデータのまま読みやすくなり、コメントも書けるようになります。

逆方向では、JSON に置き場所のないものが失われます。コメント、アンカー、複数行文字列のいくつかの書き方の区別です。そのため Kubernetes のマニフェストを JSON 経由で往復させると、中の説明用コメントがすべて取り除かれます。これは、半年後にそのファイルに戻ってくるまで誰も気付かない類の損失です。

YAML モードを持つエディターを使ってください。インデントのガイドを表示し、タブを変換し、パイプラインに発見させる前にその場で構造上のエラーを示してくれます。リポジトリに入れるファイルには、コミットフックでのリンターが、設定にかかる十分の手間に十分見合います。

スキーマが存在するなら、送り出す前に検証してください。Kubernetes、OpenAPI、多くの CI システムはスキーマを公開していて、検証を行えば、パーサーは喜んで受け入れてもシステムが真夜中の三時に拒否するような、位置を間違えたキーを捕まえられます。