JSON・YAML・TOML の違い: API データと設定ファイル、どれを選ぶべきか

要約: JSON、YAML、TOMLはそれぞれいつ使うべきか

• JSON は、APIやWebhookのようにプログラム同士がデータをやり取りするときの基本形式です。
• YAML は人が読む宣言的な設定に向いていますが、インデントそのものが文法なので、検証を怠ると危険です。
• TOML はコメントを残しつつ、比較的シンプルなプロジェクト・ツール設定に向いています。
• 形式そのものより重要なのは、その形式を読み込むツールのスキーマとCI検証です。

JSON、YAML、TOMLはいずれもオブジェクトやリストのような構造を表現できます。そのため拡張子を変えるだけで似たように見えてしまいます。しかし実際には、一方はデータ交換、一方は人が読む宣言、一方は設定ファイルを目的として設計されています。形式を選ぶときに大事なのは「文法がきれいかどうか」ではなく、誰が、いつ、どんなツールで編集し読むのかをまず決めることです。

API・Webhook・保存データならJSON

JSONは名前と値の組み合わせ、順序を持つ配列、そして文字列・数値・真偽値・nullという限られた値だけを使います。文字列はダブルクォートで囲み、カンマと中括弧で構造を表します。

{
  "userId": "u_42",
  "notifications": true,
  "tags": ["beta", "mobile"]
}

この制約は、不便さよりもメリットの方が大きいものです。ブラウザとサーバー、異なる言語で書かれたサービス同士が同じデータを解釈する必要があるとき、あいまいさを減らしてくれます。JSONは標準ライブラリやHTTPツールのサポートが広く、REST API、イベント、Webhook、キャッシュデータに向いています。一方で、標準のJSONにはコメントがありません。理由を長く書き残したい運用設定では、この欠点が大きくなります。

長く宣言的な設定ならYAML

YAMLはインデントでネスト構造を表現し、コメントも許容します。読み手が項目の階層をすぐに把握できるため、CI/CDやKubernetesのように宣言が長くなるファイルで広く使われています。

service:
  name: api
  replicas: 2
  regions:
    - icn
    - nrt

ここで重要なのは、空白が単なる飾りではなく文法そのものだという点です。インデントを1段間違えると、見た目は同じキーでも構造が変わってしまいます。YAML 1.2はJSONを部分集合として取り込みましたが、実際のサービスはそれぞれ異なるパーサー・バージョン・スキーマを使っていることがあります。コピーしたサンプルをそのまま信じるより、該当ツールの公式サンプルやformatter、linterをあわせて用意しておく方が安全です。

プロジェクト設定ならTOML

TOMLは、人が読みやすい最小限の設定形式を目指しています。key = value、[table]、配列、#コメントというルールが明確です。RustのCargo.tomlやPythonのpyproject.tomlのように、プロジェクトのメタデータやツールのオプションを記述するのに自然に馴染みます。

TOMLは設定ファイルに焦点を絞った形式です。任意のデータを絶えず送り続けるAPIボディにはJSONほど向きませんが、人がレビューするアプリ・パッケージ設定では、コメントと表形式の構造が大きな利点になります。

こう選べばいい

形式を選んだ後にやるべきこと

まず、許可するキーと型、デフォルト値をスキーマとして定義します。JSONもパースが通るだけでは安全とは言えません。次に、フォーマット・パース・スキーマチェックをCIに組み込みます。YAMLのインデント、JSONのカンマ、TOMLの重複テーブルは、デプロイ前に検出しておく必要があります。最後に、秘密情報を形式の問題として解決しようとしないことです。APIキーやパスワードは、どの形式であってもリポジトリに含めず、デプロイ環境やシークレット管理ツールから注入してください。

結論

データ交換はJSON、人が読む宣言はYAML、人が保守するプロジェクト設定はTOMLという出発点は実用的です。ただし、実際に障害を減らす選択は拡張子だけでなく、形式+パーサー+スキーマ+検証プロセスをセットで選ぶことから生まれます。

出典

• JSON データ交換標準
• YAML 1.2.2 仕様
• TOML 1.0 仕様