YAMLとは？初心者向けに基本から実践活用、JSONとの違いまで徹底解説

「YAMLファイルを編集してください」と言われたものの、何から始めればいいかわからない。JSONとの違いも曖昧で、インデントエラーに悩まされている。そんな経験はありませんか？

この記事では、データ記述言語「YAML」について、基本概念から実践的な書き方、さらにAI時代における最新活用法まで徹底解説します。Docker Compose、Kubernetes、GitHub Actionsなど現代の開発現場で必須となったYAMLを、この機会にマスターしましょう。

読了後には、YAMLの構文ルールを理解し、エラーなく設定ファイルを書けるようになります。さらに、AIプロンプトへの応用など一歩進んだ活用法も身につきます。

LLMと相性の良いデータ記述言語「TOON」についても解説しています！
🔗JSON効率化の新常識「TOON」入門｜LLMのトークン削減でAPI費用を最大60%カットする方法

YAMLとは？

YAMLとは、人間にとって読み書きしやすいデータ記述言語です。「YAML Ain’t Markup Language（YAMLはマークアップ言語ではない）」の略称で、構造化データをシンプルな記法で表現することを目的としています。

XMLやJSONと同様に「データシリアライズ形式」の一つです。データシリアライズとは、データをファイル保存や通信できるよう直列化するフォーマットのことを指します。

YAMLの歴史

YAMLは2001年にClark Evans氏らによって開発が開始されました。当初はXMLの冗長さを解消し、人間に優しい形式を目指して作られました。

主要な歴史は以下のとおりです。

• 2001年：初期バージョンのプロトタイプがPerl言語で作成
• 2003年：Ruby言語が初めてYAMLを言語のコア機能として採用
• 2004年：YAML 1.0 公開
• 2005年：YAML 1.1 公開。JSONがYAMLのサブセットとなる
• 2009年：YAML 1.2 公開。JSONとの完全互換性を実現
• 2021年：YAML 1.2.2 公開。仕様の微修正と拡張

YAML 1.2以降では、すべての正当なJSONは正当なYAMLドキュメントとして解釈可能です。つまり、YAMLパーサでJSONファイルを読み込むことができます。2026年現在もYAML 1.2（リビジョン1.2.2、2021年公開）が最新の仕様です。

YAMLの特徴・メリット

YAMLが多くの開発現場で採用される理由を5つ紹介します。

メリット1. 可読性が高い

インデントにより直感的に階層が示されます。波括弧や大量の引用符に悩まされることなく、内容を理解できます。JSONやXMLに比べて設定ファイルのレビューが楽になります。

メリット2. 記述が簡潔

不要な記号を省けるため、手書きする量が減ります。JSONでは各項目間にカンマが必要ですが、YAMLでは改行とインデントだけで済みます。ある調査では、YAMLを使うことで設定ファイルのエラーが30%減少したという報告もあります。

メリット3. 柔軟なデータ表現

リスト、辞書、スカラー値をネストして複雑な構造を表現できます。複数行文字列や日付型など、多彩な表現力があります。XMLほど冗長ではなく、JSONにない機能も備えています。

メリット4. コメントが書ける

YAMLはコメントを書けるため、設定内容に説明を加えられます。JSONにはこの機能がなく、YAMLの大きな優位点です。チーム開発での引き継ぎや保守性の向上に貢献します。

メリット5. アンカーとエイリアスによる再利用

同じデータの繰り返しを避けるため、一度定義した値ブロックを再利用できます。DRY（Don’t Repeat Yourself）原則を適用した効率的な記述が可能です。大規模な設定でも整理して管理できます。

YAMLのデメリット・注意点

便利なYAMLですが、いくつかの注意点があります。

デメリット1. インデント依存によるエラー

YAMLはインデント量の違いやスペース/タブの混同で、簡単に構文エラーが発生します。JSONのように明確な閉じ括弧がないため、インデントを間違えると構造が大きくズレます。

ある調査によると、インデントミスはYAML関連のフォーマットエラーの約70%を占めており、プロジェクトの約30%がインデントミスによる不具合を経験しています。

YAMLではタブ文字は使用せず、スペースに統一することが推奨されています。一般的には2つのスペースを使用します。

デメリット2. 曖昧な型解釈

YAMLの型推論は便利な反面、「勝手に型変換されてしまう」落とし穴があります。例えば「yes」「no」「on」「off」といった語がブーリアン（真偽値）に変わることがあります。

2024年のConfiguration Management Reportによると、本番環境のインシデントの27%が、引用符なしのエントリによるデータ型の誤解釈に起因しています。

デメリット3. パース速度

YAMLパーサはJSONに比べて処理が複雑で、速度面で劣る場合があります。大規模データのやり取りやリアルタイム処理にはJSONの方が適しています。YAMLは設定ファイル向きであり、大量データ保存には向いていません。

YAMLとJSONの違い

YAMLとJSONは両方ともデータ表現フォーマットですが、目的や特性が異なります。以下の比較表で主要な違いを確認しましょう。

使い分けの指針

YAMLが適している場合：人間が頻繁に読み書きするデータや設定（構成管理ファイル、CI/CD定義、インフラ設定など）。可読性を最優先し、コメントで説明を書き込みたいケース。

JSONが適している場合：アプリ間のデータ通信やAPIレスポンスなど、機械処理がメインで人が直接編集しないデータ。データサイズや処理速度を重視する場合。

「人が見る設定」はYAML、「機械がやり取りするデータ」はJSONと考えると選択しやすいでしょう。Kubernetes公式もYAMLを推奨しており、JSONも受け付けますが一般にはYAML形式で書くのが慣例です。

YAMLの書き方・基本構文

YAMLの構文はシンプルですが、いくつかの基本ルールを理解する必要があります。ここでは実際のサンプルコードとともに解説します。

インデントによる階層構造

YAMLではインデント（字下げ）によってネスト（階層）を表現します。スペースでインデントを行い、ネストが深いほど右に字下げします。

address:
  prefecture: Tokyo
  city: Chiyoda-ku
  zip_code: "100-0001"

キーと値、コメントの記法

データをキーと値（Key-Value）のペアで記述します。コロン（:）の後に半角スペースを1つ入れて値を記述します。コメントはハッシュ記号（#）で始めます。

# ユーザーの基本情報
name: Taro Yamada  # 姓名
age: 30            # 年齢

リスト（配列）の表現

リストを記述するには、ハイフン（-）と半角スペースを項目の先頭に付けます。

favorite_fruits:
  - Apple
  - Banana
  - Orange

辞書（マップ）のネスト

辞書（連想配列）は、キーと値のペアをインデントによってグループ化します。

contact:
  phone: "012-3456-7890"
  email: taro@example.com
  address:
    prefecture: Tokyo
    city: Chiyoda-ku

データ型

YAMLは多くのデータ型をサポートしています。

• 文字列：ダブルクオートまたはシングルクオートで囲む、または引用符なし
• 数値：整数や浮動小数点数はそのまま記述（例：port: 8080）
• 真偽値：true / false（小文字推奨）
• null：null または ~（チルダ）と記述
• 日付：YYYY-MM-DD形式で記述（例：birthday: 1990-04-01）

# データ型の例
name: "Taro Yamada"   # 文字列
age: 30               # 整数
height: 175.5         # 浮動小数点
is_active: true       # 真偽値
nickname: null        # null値
birthday: 1990-04-01  # 日付

複数行文字列

長い文章や改行を含む文字列を扱う際に便利な記法があります。

リテラルブロック（|）：改行をそのまま保持します。

description: |
  これは複数行にわたる
  説明文です。
  改行もそのまま保持されます。

折りたたみブロック（>）：改行を空白に変換して一行の文字列にします。

summary: >
  これは長い要約文です。
  複数行に書いても
  出力時には一行になります。

アンカーとエイリアス

同じデータの繰り返しを避けるため、アンカー（&）とエイリアス（*）を使います。マージキー（<<）で辞書の内容を統合できます。

# 共通設定をアンカーで定義
default_settings: &default
  adapter: postgresql
  encoding: unicode
  pool: 5

# エイリアスで再利用
development:
  <<: *default
  database: myapp_dev

test:
  <<: *default
  database: myapp_test

production:
  <<: *default
  database: myapp_prod
  pool: 10  # 上書きも可能

よくある落とし穴と対策

YAMLには初心者がつまずきやすいポイントがあります。特に有名な「ノルウェー問題」を含め、よくある落とし穴と対策を解説します。

ノルウェー問題（Norway Problem）

YAMLで最も有名なバグの一つが「ノルウェー問題」です。ノルウェーの国コード「NO」がブーリアン値のfalseとして解釈されてしまう問題です。

# 問題のあるコード
countries:
  - GB
  - IE
  - FR
  - NO  # falseとして解釈される！

# パース結果: ['GB', 'IE', 'FR', False]

YAML 1.1では、yes、no、on、off、y、nなどがブーリアン値として解釈されます。YAML 1.2ではtrueとfalseのみが真偽値として認識されますが、多くのパーサがまだYAML 1.1準拠のため注意が必要です。

対策：文字列として扱いたい値は必ず引用符で囲みましょう。

# 正しいコード
countries:
  - "GB"
  - "IE"
  - "FR"
  - "NO"  # 文字列として正しく解釈される

バージョン番号の問題

バージョン番号も意図せず数値として解釈されることがあります。

# 問題のあるコード
version: 1.0    # 数値1として解釈される
version: 3.10   # 数値3.1として解釈される

# 正しいコード
version: "1.0"
version: "3.10"

時刻表記の問題（60進数）

YAML 1.1では、コロンで区切られた数値が60進数として解釈されることがあります。

# 問題のあるコード
time: 22:22  # 数値1342として解釈される可能性

# 正しいコード
time: "22:22"

コロン後のスペース忘れ

キーと値の間のコロンの後には必ずスペースが必要です。

# 間違い
name:value  # パースエラー

# 正しい
name: value

インデントの不統一

スペースとタブを混在させたり、インデント幅が不統一だとエラーになります。

# 間違い（タブとスペースの混在）
person:
	name: Alice  # タブを使用
  age: 28      # スペースを使用

# 正しい（スペースのみ、一貫した幅）
person:
  name: Alice
  age: 28

YAMLのベストプラクティス

YAMLコア開発チームが発表したベストプラクティスを含め、推奨される書き方を紹介します。

インデントは2スペースで統一

# 推奨
parent:
  child:
    grandchild: value

真偽値はtrue/falseのみを使用

YAML 1.2との互換性を保つため、trueとfalse（小文字）のみを使用しましょう。yes、no、on、offは避けてください。

# 推奨
is_active: true
is_admin: false

# 非推奨
is_active: yes
is_admin: no

ファイル末尾には改行を入れる

異なるパーサ間での互換性を保つため、ファイルの最後に改行を入れましょう。多くのエディタで自動設定できます。

拡張子は.yamlを推奨

.ymlと.yamlの両方が使われていますが、YAMLコア開発チームは.yamlを推奨しています。

文字列は必要に応じて引用符で囲む

特殊文字を含む文字列や、ブーリアン・数値と誤解される可能性のある値は引用符で囲みましょう。

# 推奨
country_code: "NO"
version: "1.0"
path: "C:\\Users\\name"
message: "Hello: World"

ファイルは短く保つ

1つのYAMLファイルにすべてを詰め込まず、機能ごとにファイルを分割しましょう。デバッグが容易になります。

意味のあるキー名を使う

# 非推奨
a: localhost
b: 8080

# 推奨
host: localhost
port: 8080

コメントは上の行に記述

コメントは対象の行の上に配置し、インデントを揃えましょう。

# データベース接続設定
database:
  # 開発環境用ホスト
  host: localhost
  # デフォルトポート
  port: 5432

YAMLの活用例・事例

YAMLはソフトウェア開発や運用の多くの場面で使われています。代表的な活用例を紹介します。

アプリケーション設定ファイル

Ruby on Railsでは設定ファイル（database.yml）や国際化用の翻訳ファイルにYAMLが使われています。

default: &default
  adapter: mysql2
  pool: 5
  timeout: 5000

development:
  <<: *default
  database: myapp_development

production:
  <<: *default
  database: myapp_production
  username: <%= ENV['DB_USER'] %>
  password: <%= ENV['DB_PASSWORD'] %>

Docker Compose

Docker Composeでは複数のコンテナ（サービス）を定義するcompose.yaml（またはdocker-compose.yml）を使用します。なお、Docker Compose V2以降ではファイル先頭のversion指定は不要になり、2026年現在は非推奨（obsolete）です。

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    depends_on:
      - db
    volumes:
      - ./html:/usr/share/nginx/html

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example
      MYSQL_DATABASE: myapp
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Kubernetes

Kubernetesでは、クラスタ上のリソース（PodやDeploymentなど）を定義するマニフェストにYAMLが使われています。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: "128Mi"
              cpu: "500m"

GitHub Actions（CI/CD）

GitHub Actionsでは、.github/workflows/ディレクトリにYAMLファイルを置いてパイプラインを定義します。

name: CI Build

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build

おすすめツール・エディタ拡張

YAMLを効率的に書くためのツールを紹介します。

VS Code拡張機能

コマンドラインツール

オンラインツール

yamllintの使用例

# インストール
pip install yamllint

# 基本的な使い方
yamllint config.yaml

# 設定ファイルを指定
yamllint -c .yamllint config.yaml

.yamllint設定ファイルの例：

extends: default
rules:
  line-length:
    max: 120
  indentation:
    spaces: 2
  truthy:
    allowed-values: ['true', 'false']

セキュリティ上の注意点

YAMLには便利な機能がある反面、セキュリティリスクも存在します。特に外部からのYAML入力を処理する場合は注意が必要です。

任意コード実行の脆弱性

多くのYAMLパーサには、YAMLデータをデシリアライズする際に任意のコードを実行できてしまう脆弱性がありました。

Pythonの例

# 危険なコード
import yaml
yaml.load(untrusted_data)  # 任意コード実行の可能性

# 安全なコード
import yaml
yaml.safe_load(untrusted_data)  # 安全にパース

2021年には、GoogleのTensorFlowがYAMLの脆弱性（CVE-2021-37678）を理由にYAMLサポートを廃止し、JSONへの移行を推奨しました。

各言語での安全なパース方法

セキュリティのベストプラクティス

1. 信頼できないソースからのYAMLは必ずsafe_load系の関数を使う
2. パーサのバージョンを最新に保つ（PyYAML 6.0.3が2026年現在の最新版で、既知の脆弱性が修正済み）
3. 入力のバリデーションを行う
4. 必要最小限の権限で実行する

AI時代でのYAML活用方法

大規模言語モデル（LLM）の登場により、YAMLは新たな活用シーンが広がっています。プロンプト設計やAI設定管理での活用法を紹介します。

YAMLを使ったプロンプトの構造化

ChatGPTやClaudeなどのLLMへの指示をYAML形式で記述する手法が注目されています。自然言語だけでは構造が曖昧になりがちですが、YAMLで書くと視覚的に階層構造を表現できます。

system:
  role: "シニアソフトウェアアーキテクト"
  expertise:
    - システム設計
    - マイクロサービス
    - クラウドアーキテクチャ

task:
  description: "ユーザーの技術的な質問に回答する"
  output_format: "3つのポイントで簡潔に説明"

style:
  tone: "professional"
  language: "Japanese"
  
constraints:
  - 専門用語は初出時に説明を加える
  - 具体例を含める
  - 300文字以内で回答

YAMLプロンプトによるコスト削減

ある開発者の検証によると、YAMLで構造化したプロンプトは、自然言語のみのプロンプトと比較して約30%のトークン削減を実現しました。これはLLM APIの利用コスト削減に直結します。

自然言語プロンプト（355トークン）

あなたは「アーキテクトガイド」です。個々のモジュール開発には経験がありますが、
プロジェクト全体のアーキテクチャの理解と管理スキルを向上させたいプログラマーを
支援することを専門としています...（以下長文）

YAMLプロンプト（251トークン）

system:
  role: "アーキテクトガイド"
  purpose: "開発者のアーキテクチャスキル向上を支援"
  
guidelines:
  - 図やイメージを活用して説明
  - 専門用語を避け、明確に説明
  - コードではなく概念に焦点
  - 実践的な例を重視

Prompt Declaration Language (PDL)

IBMが開発したPDLは、YAML形式でプロンプトを宣言的に記述するフレームワークです。プロンプトをコードのように管理し、再現性と保守性を向上させます。RAG、CoT、ReActなどのパターンにも対応しており、2026年現在も活発に開発が続けられています。

text:
  - role: system
    text: |
      You are a helpful AI assistant.
      You follow instructions carefully.
  - role: user
    text: ${{ input }}
  - model: gpt-4
    temperature: 0.7
    max_tokens: 200

Microsoft Semantic Kernelでの活用

Microsoft Semantic Kernelでは、YAMLでプロンプトテンプレートを定義できます。

name: GenerateStory
template: |
  Tell a story about {{$topic}} that is {{$length}} sentences long.
template_format: semantic-kernel
description: A function that generates a story about a topic.
input_variables:
  - name: topic
    description: The topic of the story
    is_required: true
  - name: length
    description: The number of sentences
    is_required: true
execution_settings:
  gpt-4:
    temperature: 0.7
    max_tokens: 500

機械学習実験の設定管理（Hydra）

Meta（Facebook）が開発したHydraは、機械学習実験の設定をYAMLで柔軟に管理します。

# config.yaml
model:
  name: transformer
  layers: 12
  hidden_size: 768

training:
  learning_rate: 0.001
  epochs: 100
  batch_size: 32
  optimizer: adam

data:
  train_path: ./data/train.csv
  valid_path: ./data/valid.csv
  test_path: ./data/test.csv

コードを変更せずに実験パラメータを差し替えられ、再現性の高い実験が可能になります。

LLMによるYAML生成・検証

LLMはYAMLの生成や検証も得意としています。

推論能力の高いモデルを使うことで、yamllintなどのツールでは検出できない論理的な矛盾まで指摘してくれる可能性があります。

YAMLに関するよくある質問

YAMLとJSONはどちらを使うべきですか？

人間が直接読み書きする設定ファイルにはYAML、APIレスポンスやプログラム間通信にはJSONが適しています。コメントが必要な場合はYAML一択です。

YAMLでタブは使えますか？

いいえ、YAMLではタブ文字を使用せず、スペースに統一することが推奨されています。一般的には2スペースを使用します。タブを使うとパースエラーの原因になります。

「yes」や「no」が意図せず変換されるのはなぜ？

YAMLの型推論により、「yes」「no」「on」「off」などがブーリアン（真偽値）として解釈されるためです。これは「ノルウェー問題」として知られています。文字列として扱いたい場合は引用符で囲んでください（例："yes"）。

YAMLファイルの拡張子は何ですか？

一般的に「.yml」または「.yaml」を使用します。YAMLコア開発チームは「.yaml」を推奨しています。どちらも機能的には同じです。

YAMLのバリデーションはどうすればいい？

以下の方法があります。

• yamllint：コマンドラインツールで構文とスタイルをチェック
• VS Code拡張機能：リアルタイムで構文チェック
• オンラインバリデータ：ブラウザで手軽にチェック
• LLM：「このYAMLに問題がないかチェックして」と依頼

YAMLは安全ですか？

適切に使用すれば安全です。ただし、信頼できないソースからのYAMLを処理する場合は、必ずsafe_load系の関数を使用してください。yaml.load()などの関数は任意コード実行の脆弱性があります。

YAML 1.1と1.2の違いは何ですか？

主な違いは以下のとおりです。

• ブーリアン値：1.1ではyes/no/on/offも真偽値、1.2ではtrue/falseのみ
• 8進数表記：1.1では0777、1.2では0o777
• JSON互換性：1.2ではJSONの完全なスーパーセット

まとめ

この記事では、データ記述言語YAMLについて、基本概念から実践的な活用法まで解説しました。最後に要点を整理します。

YAMLの公式仕様は yaml.org で確認できます。最新のYAML 1.2.2仕様は yaml.org/spec/1.2.2/ から参照できます。また、YAMLコア開発チームのベストプラクティスも yamlscript.org で公開されています。