TOML を YAML に変換

プロジェクトに関する事実——パッケージ名、対応する Python や Rust のバージョン、機能フラグ、依存関係——は年々 TOML ファイルに集まる傾向にあります。それらの事実を消費する側は、同じくらい一貫して YAML です。GitHub Actions のワークフロー、Helm の values ファイル、Ansible の変数一式、docker-compose のサービス定義です。誰かが意図してこの分裂を選んだわけではなく、二つのエコシステムがそれぞれ独立にそこへ落ち着いただけです。

そのため作業はたいてい移行ではなく転記です。値を正確に YAML の構文に移し、必要な部分を独自の形を持つファイルへ移す。この違いは大切で、「正しい出力」の意味を変えます。出力は妥当なワークフローである必要はなく、バージョン番号を打ち直さずに拾い上げられる忠実な表現であれば十分です。

TOML は数少ない、本物の日付型と日時型を持つ設定形式で、引用符なしで書かれます。launch = 2026-03-01T08:00:00Z、day = 2026-03-01、at = 08:00:00 のようにです。YAML でも同じ書き方で届き、launch: 2026-03-01T08:00:00.000Z、day: 2026-03-01、at: 08:00:00.000 のように引用符が付きません。これは YAML がタイムスタンプのために予約している表記です。同じマニフェストを JSON に変換すれば、まったく同じ文字列が引用符に囲まれて出てきます。JSON にはテキストのための一つのスカラー型しかなく、それ以外に提供するものがないからです。

この違いが実際に何を意味するかは、読み込む側次第で、信頼する前に知っておく価値があります。書いたのと同じライブラリで結果を読み戻すと、YAML 1.2 のコアスキーマに従うため、これらの値はすべて文字列として返ってきます。1.2 にはタイムスタンプの解決器がないからです。PyYAML や Ruby の Psych——どちらもまだ YAML 1.1 のまま——で読めば、最初の二つは日時型になり、at: 08:00:00.000 は六十進法の数値 28800 として解決されます。オフセットも読み込み時に UTC へ正規化され、2026-03-01T08:00:00+02:00 は 06:00:00Z として返ってきます。日付が日付のまま生き延びる必要があるなら、ファイルの形に頼らず、行き先で明示してください。

[package] という見出しは、その下に 2 スペースでインデントされた値を持つトップレベルのキーになります。[tool.black] という見出しは、tool: の中に black: が入り、その中に設定が入る形になります。ドット付きの見出しは名前にドットが入っているのではなく入れ子だからです。ドット付きキーも同じ扱いで、a.b = 1 は a: の中に b: 1 が入る形になります。

並び順はパーサーが見た順で、TOML の場合はファイル冒頭の緩いキー群が先に来て、それぞれのテーブルが書かれた順に続きます。これはたいてい読みやすい結果になります。TOML はルート直下のキーを最初のテーブル見出しより前に置くよう求めているからです。動くのは、ファイル中に散らばったドット付きキーで表現されていたものです。それらは YAML の中で一つの親の下にまとめられ、読みやすくなる一方、元のテキストとは見た目が変わります。

これが本当の体制変更で、出力があまりに似ているために見落としやすい点です。TOML では enabled = true は構文がそう言っているから真偽値で、version = "1.0" は引用符があるから文字列です。何も推測されず、誤読の余地もありません。YAML では、引用符のないスカラーはパーサーが決めるものになり、だからこそ書き手は防御的に引用符を付けます。

この変換も、必要な場面ではそれを行います。数字の並びは引用符付きで出力されるので、version = "1.0" は version: "1.0" のままで数値の 1 にはなりません。引用符が付かないのは NO、yes、on、off で、YAML 1.2 の下ではこれらはただの文字列で、このファイルは 1.2 のパーサー向けに書かれているためです。PyYAML や Ruby の Psych のように YAML 1.1 をまだ実装しているパーサーで読めば、これらは真偽値になります。TOML を書く人はこれを考えたことがなく、だからこそここで説明する価値があります。

繰り返し現れる [[bin]] や [[tool.poetry.packages]] のようなブロックは、TOML におけるレコードのリスト表現で、これは YAML で誰もが手書きする形——ダッシュで始まる各項目、その下にインデントされたキー——に変換されます。単純な配列も同じ扱いで、要素ごとに 1 行のダッシュになり、TOML でインラインに書かれたスカラーの配列も、フロー記法ではなくブロックのリストとして出力されます。

このブロック形式は多くの YAML ツールが文書化し、多くの例が示している形なので、たいていの場合そのままワークフローや values ファイルに貼り付けられます。行き先が本当にフロー記法を求めている場合——[3.11, 3.12, 3.13] のような行列の 1 行——はその場で手直しが必要ですが、小さな修正で済みます。

スクリプトや説明文、ライセンス文の抜粋を持つ三重引用符の TOML 文字列は、行の構造を保ったまま届きます。書き出しはブロックスカラーとして行われます。キー、パイプ記号、そのあとにインデントされた本物の行が続く形で、エスケープシーケンスを含む 1 行にはなりません。

改行のない長い 1 行の値は扱いが異なります。改行はないが長い文字列は、およそ 80 桁で継続行に折り返され、YAML はその折り返しを空白として読み戻すので値そのものは変わりません。ただしファイルの中では長い URL が 2 行にまたがって見えることがあります。これは不安になるだけで実害はなく、テキストからではなく読み込んだ構造から値を取り出せば疑問は解消します。

TOML も YAML も # で始まるコメントに対応しており、マニフェストはたいていコメントだらけです。ある依存関係がパッチバージョンに固定されている理由、二つの設定のうちどちらが意図的か、マジックナンバーの由来。そのどれも生き残りません。読み込み側は途中でコメントを捨て、書き出し側にはコメントを置く仕組みがないからです。

貼り付けるだけの断片であれば気にする必要はありません。残しておきたいものであれば、これが TOML を正本として保ち YAML を生成物として扱う理由になります。同じ値を持つ二つのファイルのうち、理由が書かれているのは片方だけというのは、引き継いだ人がいずれ発見する保守上の問題です。YAML をコミットする必要があるなら、どのマニフェストから生成したか、どう再生成するかを冒頭に一言添えてください。

出力は言語の平易な部分集合を使っていて、何が欠けているかを知っておくと読むのが早くなります。アンカーもエイリアスもありません。同じ子テーブルが二回現れても参照ではなく毎回まるごと書き出されます。解析された値は別々のオブジェクトで、何も重複を除いてくれないからです。null はどこにもありません。TOML に変換すべき null がないからです。タグも明示的な型も文書区切りもありません。ファイルは 1 つの文書です。

行き先がそのどれかを求めているなら、手で足すことになります。vault タグに頼る Ansible の変数一式や、重複を避けるためにアンカーを組んだ Helm の values ファイルは、この変換が生成するファイルではなく、この変換が材料を供給するファイルです。これは YAML の限界ではなく、マニフェストがそもそもそれらを表現していなかったというだけで、何も発明はできません。

いちばん安上がりな確認は往復です。最終的にそれを読み込むもので出力を読み込み、いくつかの値をマニフェストと突き合わせてください。バージョン、日付の一つ、数字に見えて実は文字列であるべきもの、そして裸の単語の値。この四種類でほとんどの静かな不具合をカバーできます。

yq eval . out.yaml は再整形し、構文エラーがあれば報告してくれます。python -c "import yaml,sys; print(yaml.safe_load(open('out.yaml')))" は YAML 1.1 のパーサーがそのファイルをどう解釈するかを示してくれ、行き先が Ansible や古めの Kubernetes のツールならこちらが実際に効いてくる真実です。一度これをやっておくほうが、version: 1 と書いたつもりが "1.0" のはずだったパイプラインをあとから調べるより速く済みます。

このブラウザーのタブの中で、普通の JavaScript によってです。何もアップロードされず、エンジンを取得する必要もなく、アカウントも 1 日の上限もありません。何かを変換しながら通信状況を確認すれば、それを裏付けられます。

マニフェストは十分に小さいので 100 MB の無料枠は理論上の話にすぎませんが、常に公開できる内容とは限りません。プライベートなリポジトリの依存関係の一覧は内部のパッケージや内部のレジストリの名前を含み、[tool] ブロックにはホスト名やパスが入っていて、組織について本人が思う以上のことを語ってしまうことがあります。ローカルで変換していれば、そのどれも外部には漏れません。