JSON/YAML/TOML 設定フォーマット比較：開発者向け選択ガイド

JSONはJavaScript由来の軽量なクロスプラットフォーム・データ交換フォーマットとして設計されました。構文規則はECMAScript規格に準拠しており、機械によるパースの信頼性が優先されています。RFC 8259では、システム間で構造化データを伝送することが核心的な目的として明記されています。

YAML（正式名称はYAML Ain't Markup Language）は人間が読みやすい設定データとして位置付けられています。手動編集の障壁を下げることを優先し、インデントによる階層構造で階層の記述を単純化しており、非技術者が設定を編集する必要があるシナリオに適しています。

TOML（正式名称はTom's Obvious, Minimal Language）は、意味が明確な設定フォーマットとして設計されました。設定の意味は曖昧なくパース可能であるべきという考えを提唱し、明示的なセクション分割とキーバリュー構造によって解釈の曖昧さを回避しています。

3つのフォーマットの一般的な機能の違いは、設定の記述体験に直接影響します。JSONはコメント用の領域を予約しておらず、大半のパーサーはコメント構文をサポートしていません。YAMLとTOMLはいずれも単一行コメントと複数行コメントをネイティブでサポートしているため、設定の説明を記述する際に便利です。

複数行文字列と日時型の違いは、シナリオごとの要件に対応しています。YAMLは複数行の説明やテンプレート内容を記述するのに適している一方、JSONでは改行にエスケープ処理が必要で、互換性は一貫しているものの記述が煩雑です。

JSONで最も広く知られた問題は、公式にコメントがサポートされていないことです。開発者がJSONにコメントを追加すると、標準パーサーに切り替えた際にパース失敗が直接発生し、設定を読み込めなくなります。JSONCなどの派生ソリューションではコメントのサポートが追加されていますが、公式規格に取り込まれていません。

YAMLには有名なノルウェー問題が存在します。文字列が`20:03`の形式のとき、一部のパーサーが自動的にBase60の時刻型に変換してしまい、値が`1203`になり、期待される文字列値と一致しなくなる問題です。この問題はYAMLの暗黙的型変換ルールに起因しています。

TOMLには暗黙的型変換が存在しません。すべての値の型は構文によって明示的にマークされ、型が自動的に推論されることはありません。そのため、同様の曖昧さの問題が発生せず、型の結果は記述者の期待と一致します。

異なる技術スタックにおける3つのフォーマットの採用度には明確な階層が存在します。次の表は、アプリケーションシナリオごとの各フォーマットの主流な状況と、対応するエコシステムにおけるパーサーの成熟度をまとめたものです。

異なるフォーマット間で変換を行う場合、情報損失が発生する境界が決まっています。OKfmtのフォーマット変換ツールは、構文のサポート状況に基づいて有効な情報を保持し、非互換の内容を破棄します。JSONからYAMLまたはTOMLに変換する場合、ネイティブな情報の損失は発生せず、すべての構造を完全にマッピングできます。

YAMLからJSONに変換する場合、JSONがこれら2つの機能をサポートしていないため、YAMLのコメントとネイティブな日時型の情報が失われます。TOMLからJSONに変換する場合、失われるのはコメントのみで、すべての構造型を完全にマッピングできます。YAMLからTOMLに変換する場合、ネイティブな日時型は対応する形式の文字列に変換され、コメントは完全に保持されます。