ぱんだふるツール のマスコットぱんだふるツールやりたいことが、すぐできる。
開発

YAMLとJSONの違いと使い分け―設定ファイル選びの基準

YAMLとJSONはどちらもデータを表現するための形式ですが、使いどころが異なります。設定ファイルを書いていて「YAMLとJSONどちらにすべき？」と迷ったときの判断基準をまとめます。

YAMLとJSONの基本的な違い

同じデータを両形式で書くと、違いがはっきりわかります。

項目YAMLJSON
コメント書ける（# で始まる行）書けない
引用符省略できる文字列は必須（"..."）
括弧・波括弧不要必須
可読性高いプログラム向き
言語サポート広い（一部制限あり）ほぼ全言語対応

YAMLが向いている場面

  • DockerやKubernetesの設定ファイル（docker-compose.yml、kubernetes manifestなど）
  • CIの設定（GitHub Actions の .github/workflows/*.yml など）
  • アプリの設定ファイル（コメントで説明を残したい場合）
  • 人間が手で書き直す機会が多いファイル

YAMLはコメントが書けるため、設定の意図を残しやすい利点があります。インデントで構造を表すため、ネストが深い設定でも波括弧・角括弧なしで読み書きできます。

JSONが向いている場面

  • REST APIのリクエスト・レスポンス
  • package.jsonなどのツール設定
  • プログラム間のデータ交換
  • データベースや設定ストアへの保存

JSONはほぼすべてのプログラミング言語で標準ライブラリとしてパース・シリアライズができます。ブラウザのJavaScriptではJSON.parse()とJSON.stringify()だけで扱えるため、APIとのやりとりに最適です。

YAMLとJSONを変換したいとき

Kubernetes用のYAML設定をAPIに渡すためJSON化したい、あるいはAPIから受け取ったJSONをYAMLの設定ファイルに落とし込みたいという場面はよくあります。YAML ↔ JSON 変換ツールに貼り付けるだけで、どちらの方向にも変換できます。入力した内容はサーバーに送信されないため、APIキーや内部の設定をそのまま貼り付けて確認できます。

よくある落とし穴

  • YAMLのインデントはスペースのみ（タブは使えない）。タブが混じっているとパースエラーになります。
  • コロンの後はスペースが必要（key:valueはNG・key: valueがOK）。
  • JSONのコメントはYAMLに変換しても復元されない。コメントはYAMLのみの機能です。
  • 数字に見える文字列は引用符が必要（例：郵便番号"100-0001"は引用符なしだと文字列か数式かあいまい）。

YAMLのアンカーとエイリアス

YAMLには、同じ内容を使い回す仕組みがあります。& で名前を付け（アンカー）、* で参照します（エイリアス）。CI設定のように似たブロックが繰り返される場面で効果を発揮します。

defaults: &defaults
  runs-on: ubuntu-latest
  timeout-minutes: 10

job-a:
  <<: *defaults
  name: テスト

job-b:
  <<: *defaults
  name: ビルド

JSONにはこの仕組みがないため、同じ内容を毎回書くことになります。設定ファイルでYAMLが好まれる理由の一つです。

インデント事故を防ぐ

YAMLはインデントで構造を表すため、スペースの数を間違えると意味が変わります。次の設定をエディタに入れておくと事故が減ります。

  • タブをスペースに自動変換する（YAMLではタブが使えません）
  • 不可視文字（スペース・タブ）を表示する
  • YAMLの構文チェック拡張機能を入れる
  • 保存時に自動整形する

階層が4段以上深くなったら、構造そのものを見直すサインです。読みやすさのために生まれた形式なのに読めなくなっては本末転倒です。

スキーマで検証する

JSONにはJSON Schemaという仕様があり、「このキーは必須」「この値は数値」といった制約を定義して自動検証できます。YAMLもJSONに変換できるため、同じスキーマで検証可能です。

設定ファイルのミスを実行前に見つけられるため、CIやデプロイ設定のように「壊れると止まる」ファイルでは導入する価値があります。

実務での使い分け

用途選ぶ形式理由
CI・デプロイ設定YAMLコメントが書ける・人が読み書きする
APIのやり取りJSONパーサが標準で用意されている・高速
アプリの設定ファイルYAML / TOML人が編集するため
ログ出力JSON1行1レコードで機械処理しやすい

この記事で使うツール

🔄 YAML ↔ JSON 変換 →

YAMLとJSONを相互変換。設定ファイルの書き換えやAPIレスポンスの確認に。

← ブログ一覧へ