YAML はホワイトスペースに意味があるため、紛れ込んだ tab や不揃いなインデントは見た目が乱れているだけでなく、意味を変えたりパースを壊したりします。YAML formatter はこれを解決します：YAML を一貫した深さで再インデントし、スペーシングを正規化し、（必要なら）key をソートして、ファイルを読みやすく、差分もきれいに保ちます。本ガイドでは、YAML formatter が何をするか、強制されるインデント規則、注意すべき型の落とし穴、そしていつ YAML をフォーマットすべきか・いつ JSON に変換すべきかを解説します。
YAML Formatter は何をするか
formatter は YAML をデータ構造にパースし、一貫したスタイルで再シリアライズします。データは不変 —— 見た目だけが正規化されます：
- 再インデント：すべてのレベルを固定幅（よく使われるのは 2 スペース）に統一し、tab をスペースに置換
- スペーシングを正規化：コロン周り、リストのダッシュ、インライン集合の周り
- オプ ションで key をソート：canonical で diff にも優しい順序に
- 副作用として検証 —— パースできなければ、まず修正すべき構文エラーがあることになります
# 前 —— インデントがまちまちで読みにくい
server:
host: api.example.com
ports:
- 8080
- 8443
database: {name: mydb, pool: 5}
# 後 —— 2 スペースインデント、正規化済み
server:
host: api.example.com
ports:
- 8080
- 8443
database:
name: mydb
pool: 5なぜ YAML をフォーマットするか
- 可読性 —— CI パイプライン、Kubernetes マニフェスト、Docker Compose ファイルは深くネストするので、一貫したインデントで読みやすくなります。
- きれいな diff とレビュー —— 正規化されたフォーマット（と key ソート）により、PR には実際の変更だけが映り、ホワイトスペースのノイズが消えます。
- 早めのエラー検出 —— フォーマットは妥当な YAML でしか成功しないので、formatter はそのまま簡易バリデータになります。
- チームでの一貫性 —— 著者ごとのインデント癖ではなく、一つのスタイルを自動適用。
Formatter が強制するインデント規則
YAML のエラーのほとんどはインデントエラーで、まさにそれを formatter が標準化します：
- スペースのみ —— tab は使わない。 YAML はインデントへの tab 文字を禁じています。1 つの tab が最もよくある「なぜパースされない？」YAML バグです。
- 一貫した深さ。 兄弟 key は親に対して同じスペース数でインデントされる必要があります。formatter はすべてを一つの固定幅に書き換えます。
- リスト配置。 ブロックシーケンス（
-）の要素は key の下に揃えます。ダッシュをインデントするか揃えるかを formatter が正規化します。
再フォーマット時の型の落とし穴
フォーマットはデータを保ちますが、引用符のない値については YAML の型推論で驚くことがあります —— 出力を信頼する前に知っておく価値があります：
- 「Norway problem」。 引用符なしの
NO、yes、on、offは真偽値として読まれる可能性があるため、国コードNOがfalseに化けます。文字列のままにしたい値は引用符で囲みましょう。 - 先頭ゼロと巨大数。
007は数値として読まれると先頭ゼロが落ちることがあります。非常に大きな整数では精度が失われることもあります。文字列を維持すべき ID は引用符で囲みましょう。 - 日付とタイムスタンプ。 一部のパーサは引用符のない日付風文字列をタイムスタンプ型に強制変換します。リテラル文字列が欲しければ引用符で囲みます。
ブロックスタイル vs フロースタイル
YAML にはコレクションを書く方法が 2 つあります：block（インデント、行指向）と flow（インライン、JSON 風で [] / {}）：
# block
ports:
- 80
- 443
# flow（同じデータ）
ports: [80, 443]formatter は可読性のため通常 block スタイルに揃えます。flow スタイルは JSON 互換で、JSON 専用のツーリングに YAML を埋めるときに便利ですが、ネストが深くなるほど読みにくくなります 。
アンカーとエイリアス：再利用可能な断片
& はアンカーを印付け、* がそれを参照します。サービス間でコピー&ペーストせずに設定を共有するのに便利で、formatter はこれらを保持します：
defaults: &defaults
retries: 3
timeout: 30
api:
<<: *defaults
url: https://api.example.com
worker:
<<: *defaults
url: https://worker.example.com注意：JSON に変換するとアンカーとエイリアスは 消失 します —— JSON には参照型がないため値はインライン展開されます。YAML → JSON → YAML のラウンドトリップでは失われます。
パースの先の Lint：yamllint
formatter は形を整え、yamllint はスタイルガイド（行長、key 順、ドキュメント開始マーカー、truthy 値、コメントの空白）を強制します。CI ではペアで使い、まず format、次にチームが選んだルールで lint。
YAML をフォーマットするか、JSON に変換するか
フォーマットはファイルを YAML のまま保ちます —— 人が編集を続ける場合に最適。JSON 変換はプログラムが消費する場合に向きます（多くのアプリは実行時に JSON しかパースしません）。YAML 1.2 は JSON の厳密な上位集合なので、データ的にはロスレスです。YAML を JSON に変換 と JSON vs YAML で使い分けを参照。
ブラウザで YAML をフォーマット＆検証
YAML を fixjson の YAML バリデータ&フォーマッタ に貼り付けて、Format YAML をクリックすれば再インデント&正規化、To JSON で変換できます。 構文エラーの正確な行番号を報告し、すべてブラウザで動作 —— アップロードなし —— ホスト名やシークレット、社内設定を含む設定ファイルには重要です。
よくある質問
YAML formatter は何をしますか？
YAML をパースして、一貫したインデントとスペーシング（オプションでキーソート付き）で再シリアライズします。データは不変 —— フォーマットだけが正規化されます。
なぜ私の YAML はパースに失敗するのですか？
ほぼ常にインデント：tab 文字（YAML はインデントに tab を禁止）か、兄弟 key の深さ不一致です。formatter はすべてを 1 つのスペース幅に書き換えるので、これらの大半を表面化し修正します。
YAML のフォーマットはデータを変えますか？
いいえ —— 空白と key 順だけです。ただし引用符のない値には注意：YAML が型を推論する場合があります（「Norway problem」）。NO や 007 のように文字列のままであるべき値は引用符で囲みましょう。
YAML をフォーマットすべきか、JSON に変換すべきか？
人が編集を続けるならフォーマット、プログラムが消費するなら JSON 変換。多くのチームは YAML で書き、ロード時に JSON に変換します。
関連ツール & ガイド
- YAML バリデータ & フォーマッタ —— ブラウザで YAML をフォーマット、検証、変換
- YAML を JSON に変換 —— 変換とインデントの落とし穴
- JSON vs YAML —— 違いと使い分け
- JSON のフォーマット方 法 —— JSON 版