How to Format JSON: Methods, Tools & Best Practices

JSONフォーマットが重要な理由

フォーマットされていないJSONは技術的には有効ですが、人間にとっては扱いにくいものです。ネストされたオブジェクトや配列の単一行の塊は、デバッグセッション中にスキャンするのがほぼ不可能で、コードレビューを推測ゲームに変えてしまいます。

適切にフォーマットされたJSONには、3つの即時の利点があります：可読性 — キーと値の階層を視覚的に追跡できること；デバッグ可能性 — 差分ツールやエラーメッセージが実際に意味のある行番号を参照すること；そしてコラボレーション — チームメイトがあなたのAPIレスポンスのフィクスチャや設定ファイルを一目で理解できることです。

フォーマットは微妙なバグを防ぐこともできます。JSONがミニファイされると、誤って配置された括弧や重複したキーを見逃すのが簡単です。構造を展開することで、これらの問題が目立つようになります。

JSONフォーマットのルール

ツールを手に取る前に、「フォーマットされたJSON」が実際に何を意味するのかを理解することが役立ちます。JSON仕様（RFC 8259）は、ホワイトスペースのルールを義務付けていません — フォーマットは純粋にプレゼンテーションの問題です。とはいえ、コミュニティは明確な慣習に落ち着いています：

• 各キーと値のペアはそれぞれ独自の行に置かれます。
• ネストされたオブジェクトと配列は親よりも1レベル深くインデントされます。
• コロンはキーの後に、1つのスペースで区切られます：“key”: “value”。
• カンマは各行の末尾に（先頭ではなく）表示されます。
• 開き括弧とブラケットはキーと同じ行に置かれ、閉じるものは親のインデントレベルに揃えられます。

以下は最小限の例です。このミニファイされたJSON：

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

は、2スペースのインデントでフォーマットされると次のようになります：

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

JSONをフォーマットする3つの方法

すべてのアプローチは、オンラインツール、コマンドラインユーティリティ、またはアプリケーションコード内でのプログラムによるフォーマットのいずれかに分類されます。適切な選択は、ワークフローのどこにいるか、どのくらいの頻度で必要かによって異なります。

1. オンラインツール

ブラウザベースのフォーマッターは、一度限りのペイロードをきれいに印刷する必要があるときの最速の方法です — 貼り付けて、ボタンをクリックし、結果をコピーします。インストールするものはなく、ターミナルに切り替える必要もありません。

オンラインツールは、迅速なデバッグ、非技術的な利害関係者とフォーマットされたスニペットを共有する場合、またはソフトウェアをインストールできないマシンで作業しているときにうまく機能します。欠点は、自動化されたパイプラインに統合できないことです。

自分で試してみてください： どんなJSONでも、私たちのJSONフォーマッターに貼り付けて、選択したインデントで瞬時に美化してください。

2. コマンドラインツール

ターミナルで作業する場合、2つのコマンドがほぼすべてのフォーマットニーズをカバーします：

Pythonの組み込みjson.toolモジュール — Pythonがインストールされた任意のマシンで利用可能で、追加のパッケージは必要ありません：

echo '{"name":"Alice","age":30}' | python -m json.tool

これにより、整然とインデントされたJSONが標準出力に出力されます。ファイルを通してパイプすることも簡単です：

python -m json.tool data.json > data-formatted.json

jq — 軽量で目的に特化したJSONプロセッサ。最も簡単なフォーマットコマンドは、単にアイデンティティフィルターです：

cat data.json | jq '.'

jqはほとんどのターミナルで構文ハイライトも追加し、フィルターをチェーンして変換とフォーマットを1回のパスで行うことができます。JSONを処理するシェルスクリプトのための選択肢です。

両方のコマンドはCIパイプラインにチェーンすることができます。たとえば、リポジトリ内のすべてのJSON設定ファイルが一貫してフォーマットされるように、プリコミットフックでjq --sort-keys .を実行することができます。

3. プログラムによるフォーマット

アプリケーションコードを書いているとき、ほとんどの言語ではJSONをフォーマットするのはワンライナーです。

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

JSON.stringifyの第3引数はインデントを制御します。2を渡すと2スペース、4を渡すと4スペース、または"\t"を渡すとタブになります。

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

プログラムによるフォーマットは、アプリケーションの一部としてJSONを生成する際に不可欠です — 設定ファイルの作成、APIレスポンスのフィクスチャの作成、またはドキュメントの生成などです。出力を完全に制御できます。

フォーマットアプローチの比較

状況に応じて適切な方法を選ぶためのクイックリファレンスです：

基準	オンラインツール	CLI (jq / json.tool)	プログラムによる
使いやすさ	貼り付けてクリック	ワンライナーコマンド	コードコンテキストが必要
一度限りのタスクの速度	最速	速い	遅い（スクリプトが必要）
自動化 / CI	適していない	優れた	優れた
カスタマイズ	限定的	中程度（フラグ）	完全な制御
オフラインで動作	いいえ	はい	はい
大きなファイルを処理	ブラウザの制限	ストリーム処理が得意	実装による

インデントの議論：2スペース vs 4スペース vs タブ

これは、熱を生むよりも光を生むことが少ない議論の一つですが、各オプションを好む実用的な理由があります。

2スペース

JSONで最も一般的な選択肢です。深くネストされた構造をコンパクトに保ちながら、明確な視覚的階層を提供します。ほとんどのJavaScriptエコシステムツール（ESLint、Prettier、npmのpackage.json）はデフォルトで2スペースです。Web APIやNode.jsプロジェクトで作業している場合、これは安全なデフォルトです。

4スペース

Pythonに関連するワークフローや一部のエンタープライズJavaショップで人気があります。余分な幅はネストレベルをより明確にし、大きな設定ファイルを読む際に役立ちます。トレードオフは、深くネストされたJSONが画面の右端にすぐに押しやられることです。

タブ

タブは各開発者がエディタ内で自分の視覚的幅を設定できるようにします。理論的には理想的に聞こえますが、実際にはほとんどのJSONツールやリンターはスペースを期待します。また、タブはWebベースの差分ビューアやGitHubのPRで一貫してレンダリングされません。

各々の使用時期：

• 2スペース — Webプロジェクト、JavaScript/TypeScriptコードベース、APIペイロード。コミュニティの標準。
• 4スペース — Python重視のチーム、大きな設定ファイルで明確さがコンパクトさに勝る場合。
• タブ — 混合言語の好みと厳格なアクセシビリティ要件を持つモノレポ（タブはユーザー設定の幅を許可します）。

最も重要なのは、プロジェクト内での一貫性です。1つを選んで、それを強制してください。

キーのソート

ほとんどのフォーマッターは、オブジェクトキーをアルファベット順に並べ替える「キーをソート」オプションを提供します。これは単なる見た目の問題ではなく、バージョン管理に実際の利点があります。

キーがソートされると、差分が意味のあるものになります。ソートなしでは、2人の開発者が異なる順序で同じキーを追加する可能性があり、実際の変更を隠すノイズの多い差分が生成されます。ソートされたキーはこれを完全に排除します。

ソートされたキーは、大きな設定ファイルをスキャンするのも簡単にします。探しているキーがわかっていれば、検索せずにそのアルファベット順の位置にジャンプできます。

唯一の注意点：一部のJSONファイルには意図的なキーの順序があります（例えば、package.jsonでは、慣習によりnameとversionが最初に来ます）。その場合は、元の順序を保持してください。

jqでキーをソートするには：

jq --sort-keys '.' data.json

JavaScriptでは、リプレイサー関数を渡すか、json-stable-stringifyのようなライブラリを使用して決定論的なキーの順序を実現します。

VS Codeでの保存時自動フォーマット

最良のフォーマットは、考えなくてもよい種類のものです。VS Codeは、JSONファイルを保存するたびに自動的にフォーマットできます。設定方法は次のとおりです：

ステップ1： 設定を開き（macOSではCmd+,、Windows/LinuxではCtrl+,）、次のエントリを追加します：

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

ステップ2： まだインストールしていない場合は、Prettier - Code formatter拡張機能をインストールします。これにより、プロジェクト内の他のすべての言語とともにJSONフォーマットが処理されます。

ステップ3： チーム全体で設定を標準化するために、プロジェクトルートに.prettierrcを作成します：

{
  "tabWidth": 2,
  "useTabs": false
}

これで、プロジェクト内のすべてのJSONファイルが、誰が編集しても同じようにフォーマットされます。プルリクエストでのフォーマットのみの差分はもうありません。

エッジケースの処理

ほとんどのフォーマットツールは標準JSONを問題なく処理しますが、いくつかの状況ではつまずくことがあります：

• 大きな数 — JSONは整数と浮動小数点数を区別しません。一部のフォーマッターは1.0を1に再フォーマットしたり、非常に大きな整数の精度を失ったりすることがあります。精度が重要な場合は、出力を確認してください。
• Unicodeエスケープ — フォーマッターが\u00e9をリテラル文字éに変換したり、その逆を行ったりすることがあります。どちらも有効なJSONですが、変更が予期しない差分を引き起こす可能性があります。
• 空のオブジェクトと配列 — 一部のフォーマッターは{}を複数行に展開します。他のものはコンパクトに保ちます。これはスタイルの好みですが、ツールによって異なる可能性があることに注意してください。
• 末尾の改行 — POSIXの慣習では、テキストファイルは改行で終わるべきです。ほとんどのフォーマッターは改行を追加しますが、すべてではありません。これがCIにとって重要な場合は、.editorconfigを確認してください。

ワークフローの一部としてのフォーマット

最も効果的なチームは、JSONフォーマットをコードフォーマットと同じように扱います — 自動化された、交渉の余地のない開発プロセスの一部として。

プリコミットフック： huskyとlint-stagedのようなツールを使用して、すべてのコミット前にJSONファイルにPrettierやjqを実行します。これにより、コードベースに入る前にフォーマットの問題をキャッチできます。

CIチェック： CIパイプラインにフォーマットチェックを追加し、適切にフォーマットされていないJSONファイルがあれば失敗するようにします。Prettierには、まさにこの目的のための--checkフラグがあります。

エディタ統合： 保存時のフォーマットは手動フォーマットを完全に排除します。共有設定ファイルと組み合わせることで、すべてのチームメンバーが同一の出力を生成することを保証します。

目標は、フォーマットを目に見えないものにすること — 自動的に発生するものにして、開発者がJSONファイルの実際の内容に集中できるようにすることです。

自分で試してみてください： フォーマットされていないJSONを私たちのJSONフォーマッターに貼り付けて、瞬時に美化してください。また、フォーマット前に構造的なエラーをキャッチするためにJSONを検証することもできます。