Zenn
Accenture Japan (有志)
🏘️

YAML入門：設定ファイルでよく見る「読みやすい」書き方

マッサン (Masanori Yoshida)
に公開
YAML
tech

はじめに

システム開発を進めていると、「設定ファイル」と呼ばれるものに触れる機会が増えてきます。アプリケーションの動作を調整したり、サーバーの構成を定義したりする際に使われるファイルです。こうした設定ファイルを記述する方法の一つとして、「YAML（ヤムル）」が広く使われています。

もしかしたら、DockerやKubernetesといった技術の学習中や、CI/CDツールの設定などで、.yaml や .yml という拡張子のファイルを目にしたことがあるかもしれません。一見すると、ただのテキストに見えますが、そこにはデータを分かりやすく構造化するためのルールがあります。

このレポートでは、「YAMLって何？」「JSONやマークダウンとどう違うの？」「どんな時に使われて、どう書くの？」といった疑問について、ITの基礎知識がある方を対象に、分かりやすく解説していきます。設定ファイルの記述やデータ表現の選択肢として、YAMLの基本を理解しましょう。

YAMLとは？

YAMLは「YAML Ain't Markup Language」（YAMLはマークアップ言語じゃないよ）の略（元々は「Yet Another Markup Language」でした）で、人間が読み書きしやすいことを重視して設計されたデータ記述言語です。主に、プログラムの設定ファイルや、異なるシステム間でデータをやり取りする際のフォーマットとして利用されます。

一番大きな特徴は、インデント（字下げ）を使ってデータの階層構造を表現することです。プログラムを書く際にインデントでコードのブロックを示すのに似ていますね。これにより、括弧 {} や []、タグ <> といった記号を多用することなく、見た目がすっきりとした、直感的に理解しやすいデータ構造を記述できます。

YAMLは、JSON（後述する別のデータ記述言語）とできることは似ていますが、人間にとっての読みやすさをより追求している点が異なります。また、コメントを書き残せるのも便利な点です。

なぜYAMLが使われるの？

YAMLが設定ファイルなどで好んで使われる理由はいくつかあります。

  1. 人間にとって読みやすい: インデントとシンプルな構文（キーと値、リスト）により、データの構造が視覚的に分かりやすいです。設定ファイルは人間が読んで編集することも多いため、この読みやすさは大きなメリットです。

  2. 書きやすい（場合がある）: 括弧やカンマを多用しないため、特に階層構造を持つデータを記述する際には、JSONなどと比べて記述量が少なく、シンプルに書けることがあります。

  3. コメントが書ける: 設定値の意味や注意点などを、# を使ってファイル内にコメントとして書き残すことができます。これにより、後からファイルを見返したときや、他の人が読むときに、内容を理解しやすくなります。

  4. 複雑なデータ構造も表現可能: 単純なキーと値のペアだけでなく、リスト（配列）、ネストされた構造、さらには「アンカー」と「エイリアス」という機能を使って同じデータを再利用するなど、比較的複雑なデータ構造も表現できます。

  5. 多くのツールで採用: Docker Compose、Kubernetes、Ansible、GitHub Actions、GitLab CIなど、多くの開発ツールやプラットフォームが設定ファイルとしてYAMLを採用しています。これらのツールを使う上で、YAMLの知識は必須となりつつあります。

YAMLの基本的な書き方

YAMLの書き方は、いくつかの基本的なルールを覚えれば理解できます。

キーと値のペア（マッピング）

データを「名前（キー）」と「その値」のセットで表現します。キーと値の間は :（コロン）で区切り、コロンの後には半角スペースを入れます。

name: Yamada Taro
age: 30
city: Tokyo

リスト（シーケンス）

複数の項目を順序付けて並べる場合は、各項目の行頭に -（ハイフン）をつけます。ハイフンの後には半角スペースを入れます。

favorite_foods:
  - Ramen
  - Sushi
  - Curry

階層構造（ネスト）

YAMLの最も重要なルールがインデントです。データに階層を持たせる（入れ子にする）場合は、内側の要素を半角スペースでインデントします。インデントするスペースの数は通常2つまたは4つですが、同じ階層内では必ず同じ数のスペースを使わなければなりません。タブ文字は使えません。

user:
  name: Suzuki Ichiro
  age: 25
  address:
    prefecture: Osaka
    city: Osaka-shi
    zip_code: "540-0000" # 数値と解釈されたくない場合は引用符で囲む
  skills:
    - language: Python
      level: Intermediate
    - language: Java
      level: Beginner

上の例では、name, age, address, skills は user の一段下の階層（インデント2つ）、prefecture, city, zip_code は address の一段下の階層（インデント4つ）、language, level は skills リスト内の各項目の下の階層（インデント6つ）になっています。

コメント

行内に # を書くと、それ以降、その行の終わりまでがコメントとして扱われ、プログラムからは無視されます。設定の意味などをメモするのに使います。

# データベース接続設定
database:
  adapter: postgresql
  host: localhost # 開発環境ではlocalhost
  port: 5432

複数行の文字列

長い文字列や改行を含む文字列を書きたい場合は、| や > を使うと便利です。

  • | (Literal Block Scalar): 改行をそのまま保持します。
    description: |
  これは複数行にわたる
  説明文です。
  改行はそのまま維持されます。
  • > (Folded Block Scalar): 改行はスペースに置き換えられますが、空行は改行として保持されます。
    summary: >
  これは長い要約文です。
  途中で改行しても、最終的には
  スペース区切りの一行として扱われます。

  ただし、このように空行を挟むと、
  そこは改行されます。

複数のドキュメント

一つのYAMLファイル内に、複数の独立したYAMLドキュメントを含めることができます。各ドキュメントの開始を ---（ハイフン3つ）で示し、任意でドキュメントの終わりを ...（ピリオド3つ）で示すことができます。

---
# ドキュメント1: アプリケーション設定
app_name: MyWebApp
version: 1.0
---
# ドキュメント2: データベース設定
database:
  type: mysql
  host: db.example.com
...

YAMLはどんな時に使う？

YAMLはその特性から、以下のような場面でよく使われます。

  • 設定ファイル: Docker (docker-compose.yml), Kubernetes (マニフェストファイル), Ansible (Playbook), CI/CDツール (GitHub Actions, GitLab CI) など、多くのツールの設定記述。
  • データ交換: 人間が読み書きする必要がある、比較的構造化されたデータの交換。
  • オブジェクトのシリアライズ: プログラム中のオブジェクトの状態をファイルに保存したり、転送したりする際の形式として。（シリアライズとは、データを送受信や保存に適した形式に変換すること）
  • APIスキーマ定義: OpenAPI Specification (Swagger) など、APIの仕様を記述する際にJSONと並んでよく使われます。

注意点

YAMLを使う上で注意したい点がいくつかあります。

  • インデントが重要: YAMLではインデントが構造を定義するため、スペースの数が間違っていると、意図しない構造になったり、エラーになったりします。特に、スペースとタブを混ぜて使うことはできません。常に半角スペースを使い、同じ階層では同じ数のスペースでインデントするようにしましょう。
  • 意図しない型の解釈: YAMLは値を自動的に型解釈しようとします。例えば version: 1.0 は数値として、active: yes はブール値（真偽値）として解釈されることがあります。もし文字列として扱ってほしい場合は、`version:

"1.0" のようにダブルクォーテーションで囲むことで、確実に文字列として扱わせることができます。yes/no, on/off` などもブール値と解釈されることがあるため注意が必要です。

  • アンカーとエイリアス: YAMLには、同じデータブロックを何度も書かずに再利用するための「アンカー (&)」と「エイリアス (*)」という強力な機能があります。これは記述量を減らすのに役立ちますが、使いすぎるとかえって構造が分かりにくくなることがあります。また、エイリアスがどのアンカーを参照しているのか追うのが大変になる場合もあります。初心者のうちは、無理に使わなくても良いでしょう。

  • 複雑になりすぎる可能性: YAMLは柔軟性が高い反面、ネストが深くなりすぎたり、アンカーやエイリアスを多用したりすると、非常に複雑で読みにくいファイルになってしまう可能性があります。シンプルさを保つように心がけることが大切です。

  • セキュリティ: YAMLファイルを外部から受け取って処理する場合、特にRuby on Railsなどで過去に見られたように、安全でないデシリアライズ（YAMLデータをプログラムのオブジェクトに変換する処理）による脆弱性が存在する可能性があります。信頼できないソースからのYAMLデータを扱う際には注意が必要です。

  • ツールによる解釈の違い: YAMLの仕様は比較的大きい（JSONより複雑）ため、利用するツールやライブラリによって、解釈のされ方やサポートされている機能に若干の違いが出ることがあります。特定のツールでしか動かないような書き方は避けるのが無難です。

まとめ

YAMLは、インデントを使ってデータの階層構造を表現する、人間にとって読み書きしやすいデータ記述言語です。特に、Docker、Kubernetes、各種CI/CDツールなどの設定ファイルを記述する際によく使われます。

YAMLのポイント:

  • インデント（半角スペース）で構造を示す。タブは使えない。
  • 基本的な構成要素は「キー: 値」のペア（マッピング）と - 値 のリスト（シーケンス）。
  • コメント (#) が書けるので、設定の意味などをメモしやすい。
  • JSONと比べて、括弧やカンマが少なく、見た目がすっきりしている。
  • 多くの開発ツールで設定ファイル形式として採用されている。

マークダウンが主に文章の構造を示すのに対し、YAMLはデータ（特に設定値）の構造を示すのに適しています。JSONもデータ構造を示しますが、YAMLの方が人間にとっての読みやすさを重視しています（ただし、JSONの方が機械にとってはより厳密で処理しやすい側面もあります）。

YAMLを扱う際は、インデントのルールを正確に守ること、意図しない型解釈に注意すること、そして複雑にしすぎないことを意識すると良いでしょう。多くのツールで使われているため、基本的な読み書きができるようになっておくと、システム開発の様々な場面で役立ちます。まずは、身近なツールの設定ファイルなどを読んで、その構造に慣れることから始めてみてください。

Accenture Japan (有志)
Accenture Japan (有志)

アクセンチュア株式会社に所属する社員有志による運営です。アクセンチュアの社員による様々な発信をまとめています。なお、投稿内容は社員個人の見解であり、所属する組織を代表するものではありません。

Discussion