JSON を YAML に変換

これは「何を代償に払うのか」という問いへの答えが本当に「何もない」になる、このページ群の中で唯一の変換です。2009 年に発表され、それ以来仕様が保っているバージョンである YAML 1.2 は、JSON を部分集合として定義しています。有効な JSON 文書はすでに有効な YAML 文書です。この変換は、同じ木構造を別のスタイルで再度書き出しているだけです。

そのため、このページの残りは普通とは違う内容になります。警告すべき非可逆な段階はなく、平坦化もなく、近似しなければならない型もありません。代わりにあるのは、結果がどう読まれるかについての一連の問いで、それはどんなデータの損失よりも重要だとわかります。

書き出し処理は YAML 1.2 に従っており、そこでは no、yes、on、off は普通の文字列です。そのため JSON の値 "no" は、引用符なしの素の no として書かれ、その文書を 1.2 のパーサーで読み戻すと、元と同じ文字列が返ってきます。これは正しい振る舞いで、完全に往復します。

YAML 1.1 は意見が異なります。同じ単語を真偽値として解決し、Ansible や多くの Python ツール、数えきれない社内スクリプトが使う PyYAML は 1.1 の読み手です。2 文字の国コード、回答欄、consent という名前の列——値は文字列の no として入りますが、false として出てきます。下流のどこかに Python のツールがあるなら、変換したあとにそれらの値を手作業で引用符付きにしてください。小さな編集で済みますが、この変換が正しいのに誤って動作するファイルを生む、もっとも起こりやすい原因です。

引用符を付けるかどうかは値ごとに判断され、素のまま書くと別のものとして読まれてしまう場合だけ付けられます。文字列 "1.0" は引用符付きになります。引用符なしだと数値になるからです。文字列 "null" も引用符付きになります。引用符なしだと null の値になるからです。ハッシュで始まる文字列は引用符付きになります。素のハッシュはコメントの開始を意味するからです。前後にスペースを持つ文字列も引用符付きになります。そうしないと YAML がそれを取り除いてしまうからです。

このルールは一貫しており、1.2 のルールです。まさに前の節の主題です。書き出し処理が引用符を付けるものはすべて YAML 1.2 のもとで意味が変わってしまうもので、素のまま残すものは 1.1 のもとでのみ意味が変わるものです。2024-01-01 のような日付の形をした文字列も同じ理由で素のまま残され、1.1 の読み手はそれをタイムスタンプに変換します。

JSON の文字列は文字どおりの改行を含められないので、JSON のマニフェストに埋め込まれたシェルスクリプトや証明書、SQL 文は、改行があるべき場所にバックスラッシュと n が並ぶ、1 つの巨大な行になります。それに対する変更をレビューするのはほぼ不可能です。

YAML のライターはそうした値をブロックスカラーとして出力します。パイプ文字のあと、テキストが独自のインデントされた行の上に、改行があるべき場所に改行として現れます。12 行のエントリーポイントスクリプトは、ファイルの中で 12 行になります。マニフェストを人がレビューする必要があるという理由で変換する人にとって、これはたいてい出力の中で最大の改善で、実際にそういう値を含むファイルに出会うまでは見えないものです。

JSON のオブジェクトの配列は、あらゆる Kubernetes や GitHub Actions の例が書かれているハイフン付きのリストに変換されます。ハイフン、続けて同じ行に最初のキー、そしてその下にインデントされた残り。コンテナー、ステップ、ボリューム、ジョブ——どれもドキュメントに示されている形で届きます。

これは正しさではなくレビューのために重要で、レビューこそこのファイルの目的です。6 つのデプロイ手順のリストを YAML で見るレビュアーは、括弧を数えなくても境界を見分けられます。この生態系がインデントの落とし穴を抱えながらもこの形式を選んだ理由です。

JSON はコメントを運びません。これはパーサーの偶然の産物ではなく、RFC 8259 の文法そのものに由来します。コメントのための構文規則が存在しないので、準拠したパーサーには受け入れるものが何もないのです。YAML は、行がハッシュで始められる場所ならどこでもコメントを運べます。生成されたマニフェストを YAML に変換する目的は、構文とはまったく関係ないことがよくあります。値の理由をその値の隣に置ける場所にすることが目的です。

出力にコメントはありません。入力側に渡せるものが何もなかったからです。それを加えることが最初に行う価値のある編集で、もっとも役に立つコメントは、あるフィールドが何であるかの説明であることはめったにありません。レプリカ数がなぜ 3 なのか、イメージタグが別のどのリポジトリと一致していなければならないか、タイムアウトを下げると何が壊れるかを書いておいてください。

YAML にはアンカーとエイリアスがあり、1 つのブロックを一度定義して 3 か所から参照できます。また 1 つのファイルの中に、3 つのハイフンで区切られた複数の文書を持てます。どちらも広く使われており——compose ファイルや Kubernetes のバンドルはこれに頼っています——どちらも JSON の元データからは出てきません。JSON にはそれを表現する方法がまったくないからです。

そのため変換されたファイルは正しく、そして平坦です。JSON の中で繰り返されているものは、YAML の中でも繰り返されます。その繰り返しをアンカーで因数分解するのは手作業の編集で、繰り返しが本物であるときだけ行う価値があります。1 つの JSON 配列に連結された複数の別々のマニフェストも同様のケースで、正しい結果は 1 つのファイルの中の複数の文書であり、これもまた変換ではなく編集です。

ライターはキーが届いた順序を保つので、apiVersion、kind、metadata はアルファベット順に並べ替えられるのではなく、もとの位置に留まります。JSON も YAML も、マッピングの順序に意味があるとは定義しておらず、多くのツールが自由に並べ替えますが、キーがアルファベット順にされたマニフェストは読みにくく、理由もなく大きな差分を生みます。

これは、出力をリポジトリにすでにあるファイルと比較するときに知っておく価値があります。もし 2 つが順序だけで違っているなら、その違いはこの変換ではなく、JSON を生成した何かに由来します。たとえばクラスターからリソースを読み戻すと、書いたときの順序ではなく API サーバーの順序でフィールドが返ってきます。

いちばんコストの低い確認は、ツール自身のドライランです。--dry-run=client 付きの kubectl apply、docker compose config、Actions ファイル用のワークフローリンター。それぞれが文書を解析し、見つけた形を報告してくれるので、ファイルを読むより早く配置間違いのキーを見つけられます。

引用符の問題を捕まえる確認は違っていて、意図的に行う必要があります。変換されたファイルの中の素の yes、no、on、off、そして引用符なしの日付を検索し、それぞれについて YAML 1.1 の読み手がいつかそれを見る可能性があるかを判断してください。1 分で済み、パーサーが警告してくれないこの変換の唯一の部分です。

この変換はこのタブの中で動きます。JSON はブラウザー自身のパーサーで解析され、YAML は必要に応じて読み込まれるライブラリで書き出されます。文書をどこかへ運ぶリクエストは発生せず、登録も 1 日の上限もなく、無料枠は 100 MB まで受け付けます。どんなマニフェストよりはるかに大きな容量です。

このページの読者にとって、これは抽象的な話ではなく実務上の懸念です。稼働中のクラスターから取り出したマニフェストには、内部のホスト名、レジストリのパス、サービスアカウント名、インフラの形が含まれます。それを公開の Web 変換ツールに貼り付けることをインシデントとして扱う組織も少なくありません。ここには貼り付けるものも送信するものもありません。