TOMLファイルとは

TOML はプレーンテキスト形式です。どのエディターでも開けます。 編集のために使われます。

拡張子は .toml、正式名称は Tom's Obvious Minimal Language です。ただしどちらも、そのファイルが中に何を持てるかほどには多くを語りません。このページの残りは、その中身についての話です。

2013 年までさかのぼります。 仕様は TOML 1.0 です。

古さが役に立つのは、ごく実務的な理由からです。形式が古いほど、それを覚える時間が多くのプログラムに与えられてきたということだからです。

仕様書がそのまま公開されているので、中身を推し量るのではなく文書を読んで実装できます。この形式が数多くのプログラムに載っているのはそのためであり、20 年前に書かれたファイルが今も開けるのもそのためです。ただし「仕様が公開されている」ことと「使用料が要らない」ことは別の話です。中でコーデックを包んでいる形式では、特許のライセンスは仕様書が答えていない別の問題として残ります。

TOML ファイルは中身をそのまま保存します。保存し直しても何も変わらないので、開いて、直して、また保存する——それを何度繰り返しても劣化は積み上がりません。これが、渡すための形式ではなく作業のための形式である理由です。

TOML ファイルにはコメントを書く方法があります。人が面倒を見るファイルと、プログラムが書き出すファイルを分けるのは、まさにこの一点です。コメントを持てない形式へ変換すると真っ先に消え、しかも誰も警告してくれません。

Visual Studio Codeが読めますし、同じ種類のプログラムならたいてい読めます。

ファイルが開かないとき、形式が悪いことはめったにありません。たいていはプログラムのほうが形式より古いのです。もっと古い形式に変換してしまうのが確実な逃げ道で、このサイトの残りの部分はそのためにあります。

これを読めるブラウザーはありません。

これを変換するいちばんよくある理由がこれです。形式が悪いのではありません。ファイルを見せたい場所が、それを読めないというだけのことです。

TOML は、開いて手を入れるために作られています。作業が続いているあいだはこの形式でファイルを持ち、完成したものが必要になるたびに、ここから書き出してください。

TOML は見た目こそ INI に似ていますが、振る舞いはデータ形式のそれです。30 と書けば整数、30.0 と書けば浮動小数点数、true は真偽値、"30" は文字列、2026-08-05 は日付です。これらすべてが仕様で定義されているため、どのパーサーも同じ解釈をし、どのプログラムも書いた人の意図を推測する必要がありません。

この一つの性質が、この形式が存在する理由の大部分です。設定にまつわるバグは、まさにこの曖昧さの周りに集中します。文字列の "false" が真として読まれる、バージョン番号が静かに浮動小数点数に変わる、ポート番号がテキストとして届く、といった具合です。型を持つ形式は、この種の問題を丸ごと取り除きます。

YAML はより多機能で、その分間違えやすく、TOML はまさにその反省から生まれました。YAML の構造はインデントで表現されるため、スペース一つの位置ずれが、エラーも出さずに文書の意味を変えてしまい、それでもファイルは解析されます。意図とは違う何かとして。

型の推測も問題です。古い YAML の no は真偽値として読まれるため、国コードや言語フィールド、回答の列が false になってしまいます。1.20 のようなバージョン番号は浮動小数点数の 1.2 になります。時刻に見える文字列が六十進数として解釈されることもあります。どれも実際の障害を引き起こしてきました。TOML にはこの問題が一つもありません。構造は明示的で、値はその構文が示すとおりの値です。

Rust が真っ先にこれを広めました。すべての Cargo プロジェクトが Cargo.toml を持っています。Python もはっきりと後を追い、pyproject.toml は今やビルド設定の標準的な置き場所で、この言語は標準ライブラリーに TOML の読み込み機能を持っています。

それ以外では、Hugo をはじめとする多くの静的サイトジェネレーター、Netlify、Poetry、Ruff、そしてインデントのリスクなしに人が編集できる設定を求めた、新しいツールの絶え間ない流れがあります。開発者向けの設定において、YAML がインフラ分野の既定になったのとほぼ同じ形で、これが既定の選択肢になりつつあります。

角括弧で囲まれた見出しはテーブル、つまり TOML における節を意味します。入れ子はドットで表現されます。[tool.ruff.lint] はテーブルの中のテーブルの中のテーブルを宣言していて、このドットは名前の一部ではなく構造そのものです。まさにここが、INI が止まり TOML が先へ進む地点です。

誰もが引っかかるのは二重角括弧です。[[bin]] を三回書くと、同じテーブルを三回定義し直すのではなく、テーブルの配列を宣言することになり、リストの中に三つの項目ができます。「同じ種類のものが複数ある」ことを表す方法で、バイナリが三つ、依存関係が四つ、著者のリストといった場合です。繰り返しの設定ブロックが静かに上書きされているように見える場合、二重角括弧を使うべきところで単一の角括弧を使っているのがほぼ間違いなく原因です。

TOML は日付と時刻を直接理解します。日付だけ、時刻だけ、オフセット付きまたはなしのタイムスタンプです。これらは整数と同じ意味での値であって、後から何かが解析しなければならない文字列ではありません。

これは小さな機能ですが、根強い煩わしさを取り除きます。公開日、有効期限、締め切り、スケジュールを含む設定は、コメントに書かれた合意済みの文字列形式や、それを利用する側ごとに再実装する必要がなくなります。形式そのものがそれを定義していて、パーサーは日付を返してくれます。

深く入れ子になったデータです。TOML は平坦で読みやすいことを目指して設計されているため、構造が三段、四段と深くなると見出しの名前が長くなり、置き換えようとしている JSON より読みにくくなります。設定が文書ツリーのように見えるなら、それはおそらく本当に文書ツリーであるべきです。

機械が生成するデータももう一つのケースです。TOML は人が編集するファイルのためのもので、JSON はプログラム同士がやり取りするファイルのためのものです。JSON のほうが小さく、解析も速く、どこでも対応しています。TOML をデータ交換形式として使うことはできますが、得るものはありません。TOML が最適化している読みやすさは、人が読む場合にのみ支払う価値のあるコストです。

どんなテキストエディターでも構いませんが、本格的な用途には TOML に対応したエディターを使う価値があります。終わっていない文字列や壊れたテーブルの見出しをその場で示してくれ、パーサーであれば少し離れた行でのエラーとして報告するところを、すぐに気付けます。

間違いの大半を防ぐ習慣が二つあります。すべてのキーは、それが属するテーブルの見出しの中に置いてください。最初の見出しより上に書かれたキーは最上位に置かれ、静かに何もしません。そして数値や真偽値を引用符で囲まないでください。引用符を付けるとそれらは文字列になり、プログラムは文字列を真偽値と比較することになり、その設定は理由もなく無視されているように見えます。