設定ファイルで読むYAML入門：JSONとの違いとつまずきどころ

YAMLは、設定ファイルを人が読み書きしやすくするためによく使われるデータ記法です。WordPress周辺のDocker環境、GitHub Actionsの自動デプロイ、サーバー設定、静的サイト生成ツールなどで、.ymlや.yamlというファイル名を見かけたら、多くの場合はYAMLで書かれています。

結論から言うと、YAMLは「人が編集する設定」に向き、JSONは「プログラム同士がやり取りするデータ」に向きやすい形式です。どちらもキーと値、配列、入れ子構造を表せますが、YAMLはコメントや改行を使って説明を書きやすく、JSONは構文が厳密でAPIレスポンスや機械処理に向いています。

この記事では、YAMLの基本、設定ファイルで使われる理由、JSONとの違い、実務でつまずきやすい書き方をまとめます。

• YAMLはインデントで階層を表す設定向きの記法
• JSONは波括弧 {} と角括弧 [] で構造を表すデータ交換向きの記法
• YAMLではタブではなくスペースを使う
• on、yes、数値っぽい文字列などは、ツールによって解釈差が出ることがある
• 認証情報やAPIキーはYAMLに直書きせず、環境変数やシークレット管理を使う

YAMLとは何か

YAMLは、データをテキストで表すための記法です。公式仕様では、設定ファイル、ログ、言語をまたぐデータ共有などに使えるデータシリアライズ言語として説明されています。

「データシリアライズ」と聞くと難しく見えますが、実務では次のように考えると十分です。

• name: blog のように、項目名と値を書く
• インデントで親子関係を表す
• - でリストを書く
• # でコメントを書く

たとえば、WordPressをローカルで動かすDocker Composeのような設定では、サービス名、使用するイメージ、ポート番号、環境変数などを1つのファイルにまとめます。

services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: example

  db:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: example
      MYSQL_ROOT_PASSWORD: rootpass

ここでは、services の下に wordpress と db という2つのサービスがあります。wordpress の中には、image、ports、environment という設定が並んでいます。

このように、YAMLは「設定のまとまり」を上から順に読める形にしやすいのが特徴です。

なぜ設定ファイルでYAMLがよく使われるのか

YAMLが設定ファイルで選ばれる大きな理由は、人が編集する前提のファイルを読みやすく保ちやすいからです。

GitHub Actionsのワークフローは .github/workflows ディレクトリに .yml または .yaml ファイルとして置きます。Docker Composeでも、Compose Specificationに沿ってサービス、ネットワーク、ボリュームなどを設定ファイルで定義します。

コメントを書ける

設定ファイルでは、なぜその値にしたのかを残したい場面があります。JSONは標準仕様としてコメントを持ちませんが、YAMLでは # を使えます。

server:
  port: 8080 # ローカル確認用。公開環境では80または443を使う
  debug: false

このコメントは、あとから設定を読む人に効きます。特にサーバー運用や自動化では、「なぜこの値なのか」が分からない設定ほど変更しづらくなります。

入れ子が見やすい

YAMLはインデントで階層を表します。Web制作や自動化の設定では、1つの処理の中に複数の条件や手順が入ることが多いため、入れ子構造を読みやすく書ける点が便利です。

name: deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Show message
        run: echo "Deploy workflow started"

この例では、on が実行条件、jobs が実行する仕事、steps が具体的な手順です。JSONでも同じ内容は書けますが、設定担当者が目で追うにはYAMLのほうが短く見えます。

ただし、読みやすさはインデントに依存する

YAMLの読みやすさは、インデントが正しいことを前提にしています。1段ずれるだけで、設定の意味が変わったり、読み込みエラーになったりします。

ここがポイント: YAMLは「少ない記号で読みやすい」代わりに、スペース、改行、階層の位置がそのまま意味になります。

YAMLの基本の書き方

YAMLで最初に覚えるべき形は、キーと値、リスト、入れ子の3つです。この3つが読めれば、多くの設定ファイルを追えるようになります。

キーと値

もっとも基本の形は キー: 値 です。コロンの後ろにはスペースを入れます。

site_name: sample blog
enabled: true
items_per_page: 10

この例では、次の3つの値を持っています。

• site_name は文字列
• enabled は真偽値
• items_per_page は数値

文字列は引用符なしでも書けますが、迷う場合は引用符を付けると安全です。特に、数値に見えるIDや、true、false、null に見える文字列は引用符を付けます。

user_id: "00123"
status: "true"

リスト

リストは - で書きます。メニュー項目、許可するドメイン、実行手順などを並べるときによく使います。

allowed_hosts:
  - example.com
  - www.example.com
  - api.example.com

JSONで書くと、同じ内容は次のようになります。

{
  "allowed_hosts": [
    "example.com",
    "www.example.com",
    "api.example.com"
  ]
}

YAMLのほうが記号は少なく、コメントも挟みやすいです。一方で、JSONは構文が明確で、プログラムから生成・検証しやすい利点があります。

入れ子

入れ子はスペースで下げます。タブは使わないのが基本です。

database:
  host: localhost
  port: 3306
  name: wordpress
  user: app_user

この設定は、database の中に host、port、name、user があるという意味です。

よくある失敗は、同じ階層の項目でインデント幅がそろっていないことです。

# NG例
database:
  host: localhost
    port: 3306

port が host の下に入ったような形になっており、多くのパーサーでエラーになります。次のように同じ階層をそろえます。

# 改善例
database:
  host: localhost
  port: 3306

JSONとの違いを実務目線で見る

YAMLとJSONは似たデータを表せますが、使われる場所が違います。判断軸は「人が直接編集するか」「プログラムが頻繁に読み書きするか」です。

観点	YAML	JSON
主な用途	設定ファイル、自動化ワークフロー、CI/CD設定	APIレスポンス、データ交換、設定の機械生成
コメント	# で書ける	標準JSONでは書けない
階層表現	インデントで表す	{} と [] で表す
人間の読みやすさ	設定が長くても追いやすい	記号が多く、長い設定では重く見えやすい
機械処理	パーサーごとの解釈差に注意	仕様が小さく、APIやツールで扱いやすい

同じ設定をYAMLとJSONで比べる

まずYAMLです。

app:
  name: contact-form
  debug: false
  plugins:
    - spam-check
    - mail-log

同じ内容をJSONで書くと、次のようになります。

{
  "app": {
    "name": "contact-form",
    "debug": false,
    "plugins": [
      "spam-check",
      "mail-log"
    ]
  }
}

YAMLは、設定を人が読むときに余計な記号が少なくなります。JSONは、すべてのキーを引用符で囲み、カンマで区切るため、プログラムから見て構文を判定しやすい形です。

YAMLが向く場面

YAMLは、設定を人が直接読む・直す場面に向きます。

• GitHub Actionsのワークフロー
• Docker Composeのサービス定義
• 静的サイト生成ツールの設定
• Ansibleなどの自動化設定
• CI/CDやデプロイ手順の定義

設定値に説明コメントを入れたい、手順を上から順に並べたい、チーム内でレビューしたい。こうした場面ではYAMLの読みやすさが役立ちます。

JSONが向く場面

JSONは、プログラムが送受信するデータに向きます。

• REST APIのレスポンス
• JavaScriptで扱う設定データ
• 外部サービスへ送るリクエスト本文
• ツールが自動生成するデータ
• 厳密なバリデーションが必要なデータ交換

JSONはコメントを書けない分、形式が小さく、APIや各種ライブラリで広く扱えます。RFC 8259では、JSONは構造化データを表す軽量なテキスト形式として定義されています。

実務でよくあるYAMLのつまずき

YAMLのエラーは、内容そのものよりも「見た目のわずかな違い」で起きることが多いです。初心者がまず確認すべきポイントは、インデント、コロン、引用符、秘密情報の扱いです。

タブを使ってしまう

YAMLのインデントにはスペースを使います。エディタでタブを入れると、見た目ではそろっていてもツール側で読み込めないことがあります。

# OK: スペースで下げる
build:
  command: npm run build

対策はシンプルです。

• エディタで「タブをスペースに変換」を有効にする
• 2スペースまたは4スペースのどちらかに統一する
• 保存前にYAMLのフォーマッターやLintを通す

コロンの後ろにスペースがない

YAMLでは、キーと値を書くときに key: value の形にします。コロンの後ろのスペースを忘れると、意図通りに読まれないことがあります。

# NGになりやすい
name:sample

# OK
name: sample

URLのようにコロンを含む値を書くときは、引用符を付けると読み間違いを避けやすくなります。

endpoint: "https://api.example.com/v1/items"

文字列のつもりが別の型になる

YAMLでは、値の見た目から真偽値、数値、nullなどとして解釈されることがあります。YAML 1.2ではJSONとの整合性が重視され、古いYAML 1.1で問題になりやすかった暗黙の型解釈は整理されています。ただし、実際に使うツールやライブラリがどの仕様・実装に近いかは確認が必要です。

迷ったら、文字列として扱いたい値に引用符を付けます。

postal_code: "001-0001"
feature_flag: "on"
version: "1.0"

これは特に、ID、郵便番号、バージョン番号、電話番号、on や off のような短い値で重要です。

APIキーやパスワードを直書きする

YAMLは読みやすいので、つい設定値をそのまま書きたくなります。しかし、リポジトリに置くYAMLへAPIキー、パスワード、個人情報を直書きしてはいけません。

# NG例
api_key: "sk_live_xxxxxxxxxxxxx"

代わりに、環境変数やサービス側のシークレット管理を使います。

# 例: 環境変数名だけを設定に書く
api_key_env: "CONTACT_FORM_API_KEY"

GitHub ActionsならリポジトリのSecrets、Docker Composeなら .env ファイルや外部のシークレット管理を使うなど、ツールごとの方法に合わせます。公開リポジトリだけでなく、社内リポジトリでも同じ注意が必要です。

YAMLを確認する最小手順

YAMLは、書いたあとに必ず読み込み確認をするのが安全です。設定ファイルは、文法が正しくてもアプリ側の期待する項目名と合っていなければ動きません。

1. まず構文エラーを確認する

エディタのYAML拡張機能、オンラインではないローカルのLintツール、各サービスの検証コマンドを使います。秘密情報を含む設定は、外部のWebサービスに貼り付けないでください。

Node.js環境なら、たとえば yaml パッケージで読み込み確認できます。

npm install yaml

import fs from "node:fs";
import YAML from "yaml";

const text = fs.readFileSync("config.yml", "utf8");
const config = YAML.parse(text);

console.log(config);

この確認では、YAMLとして読めるかを見ます。ツール固有の項目名が正しいかまでは、別途そのツールの検証が必要です。

2. ツール側の期待形式と照合する

GitHub Actionsなら、on、jobs、steps、uses、run などのキーに意味があります。Docker Composeなら、services、networks、volumes などが主要なトップレベル要素です。

YAMLとして正しくても、次のようなミスはアプリ側でエラーになります。

• キー名のスペルミス
• 階層の位置が1段違う
• 値の型が違う
• 必須項目が足りない
• ツールのバージョンでサポートされない項目を使っている

たとえば、GitHub Actionsの steps はジョブの中に置きます。jobs と同じ階層に置くと、YAMLとしては読めてもワークフローとしては意図通りに動きません。

3. 変更差分をレビューしやすくする

YAMLは設定レビューでよく使われます。差分が読みやすくなるように、次の点をそろえておくと保守しやすくなります。

• インデント幅を統一する
• 関連する設定を近くにまとめる
• コメントは「なぜその値か」が必要な場所にだけ書く
• 自動生成ファイルと手編集ファイルを分ける
• 秘密情報はファイルに含めない

コメントを増やしすぎると、設定変更にコメントが追いつかなくなります。値の意味が名前から分かる場所では、コメントを省いたほうが読みやすいこともあります。

YAMLとJSONの使い分け

選び方は、どちらが上位かではなく、誰がそのファイルを主に扱うかで決めるのが現実的です。

人が読む設定ならYAML

サーバー運用、CI/CD、ローカル開発環境の設定などでは、YAMLが向いています。レビュー画面で階層を追いやすく、コメントで背景も残せます。

ただし、チームで使う場合はルールを決めておくと安全です。

• インデントは2スペースに統一する
• 文字列として固定したい値は引用符で囲む
• 秘密情報は書かない
• 変更後はツール側の検証コマンドを実行する

APIや機械処理ならJSON

APIリクエスト、APIレスポンス、JavaScriptで扱うデータ、他システムとの連携ではJSONが扱いやすいです。多くの言語に標準または定番のJSON処理機能があり、構文も小さいためです。

たとえば、WordPress REST APIのレスポンスや、外部APIから取得するデータはJSONで扱う場面が多くなります。ここでYAMLに変換してから処理する必要は通常ありません。

変換できるが、意味まで同じとは限らない

YAMLとJSONは相互に変換できる場面があります。YAML 1.2はJSONを強く意識した仕様ですが、実務ではコメント、アンカー、複数ドキュメント、ツール固有の型解釈などが絡みます。

つまり、単純な設定なら変換できますが、YAMLらしい機能を使ったファイルをJSONに変換すると、コメントや見やすさが失われることがあります。

まず覚えるべき実務ルール

YAMLを最初から仕様レベルで覚える必要はありません。設定ファイルを安全に扱うなら、まず次のルールを押さえるのが近道です。

• 階層はスペースのインデントで表す
• タブは使わない
• コロンの後ろにはスペースを入れる
• リストは - で書く
• 文字列として固定したい値は引用符で囲む
• APIキー、パスワード、個人情報は直書きしない
• YAMLとして正しいかと、ツールの設定として正しいかは別に確認する

YAMLは、読みやすい設定ファイルを書くための強力な形式です。ただし、その読みやすさは「インデントが正しい」「型の解釈を誤らない」「秘密情報を分ける」という基本に支えられています。

次にYAMLファイルを触るときは、エラー文だけを見るのではなく、まず階層を1段ずつ確認してください。多くの設定ミスは、値そのものではなく、置かれている場所の違いから起きます。

参照リンク

• YAML Ain’t Markup Language (YAML) version 1.2.2
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• GitHub Docs: Workflow syntax for GitHub Actions
• Docker Docs: Compose file reference