JSON 整形のコツとバリデーションについて

Web API の開発や設定ファイルの記述など、現代の Web 開発において JSON (JavaScript Object Notation) は避けて通れないフォーマットです。しかし、シンプルな構造ゆえに「ちょっとしたミス」でエラーになりやすく、デバッグに時間を取られてしまうことも少なくありません。

この記事では、モディッグスツールズ版 JSON 整形ツールの公式ガイドとして、JSON を扱う上での重要なコツ、バリデーションの仕組み、そしてよくあるエラーの解決方法を初心者〜中級者向けに解説します。

1. JSON とは何か

JSON は「JavaScript Object Notation」の略で、データを記述するための軽量なテキストフォーマットです。もともとは JavaScript のオブジェクト記法をベースに作られましたが、現在では Python, Ruby, Java, Go など、ほぼすべてのプログラミング言語で標準的にサポートされています。

主な特徴

• 軽量: XML などに比べてタグが少なく、データサイズが小さい。
• 可読性: 人間が読んでも理解しやすく、機械もパース（解析）しやすい。
• 汎用性: 言語に依存しないため、システム間のデータ交換に最適。

2. JSON 整形の重要性

API から返ってくる JSON データは、通信量を減らすために改行やスペースが削除された「Minify（最小化）」状態で送られてくることがよくあります。

{ "status": "ok", "data": [ { "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" } ] }

これでは構造が一目でわかりません。これを適切に改行・インデントして「整形（Pretty Print）」することは、以下の理由で非常に重要です。

• 可読性向上: データの階層構造がひと目でわかるようになります。
• レビュー効率: 設定ファイルなどの変更差分（Diff）を確認する際、整形されていないとどこが変わったか判別できません。
• デバッグ効率: 「どの階層の」「どのキー」の値がおかしいのかを即座に特定できます。

3. JSON を整形する時の具体的なコツ

きれいで扱いやすい JSON を書く・整形するためのポイントを紹介します。

インデント（2スペース vs 4スペース）

インデントの幅は好みが分かれますが、一般的には以下のように使い分けられます。

• 2スペース: 階層が深くなりやすい巨大な JSON データ向け（画面幅を圧迫しない）。JavaScript 界隈で人気。
• 4スペース: 構造をはっきりと見せたい場合や、Python などの言語文化圏で好まれる。

モディッグスツールズでは、このインデント幅を自由に切り替えることができます。

キー名の命名ルール

JSON のキー（プロパティ名）は、一般的に キャメルケース (camelCase) または スネークケース (snake_case) が使われます。プロジェクト内で統一することが最も重要です。

• 推奨: "userId", "created_at"
• 非推奨: "User-ID" (ハイフンは一部の言語で扱いにくい), "１" (全角文字)

4. JSON バリデーションの重要性

「バリデーション（Validation）」とは、データが正しい形式やルールに従っているかを検証することです。

単に「整形できるか」だけでなく、以下のような観点でチェックすることが API 事故を防ぐ鍵となります。

• 構造チェック: カンマ忘れや括弧の閉じ忘れがないか。
• 型チェック: 数値が入るべき場所に文字列が入っていないか（例: "age": "20" vs "age": 20）。

5. JSON でよくあるエラーと解決方法

初心者がやりがちなミスと、その修正方法をまとめました。

① 末尾の余計なカンマ (Trailing Comma)

配列やオブジェクトの最後の要素にカンマをつけてはいけません。

{
  "id": 1,
  "name": "Alice",  ← ここはOK
}

② キーのダブルクォーテーション抜け

JavaScript のオブジェクトとは異なり、JSON のキーは必ずダブルクォーテーション " で囲む必要があります。

{
  name: "Alice",  ← キーに " がない
  'age': 20       ← シングルクォート ' も不可
}

{
  "name": "Alice",
  "age": 20
}

③ null と "null" の違い

値が存在しないことを表す場合、文字列の "null" ではなく、予約語の null を使います。

• "value": null (正しい: 値なし)
• "value": "null" (文字列としての "null" というデータが入っている)

6. JSON Schema による高度なバリデーション

さらに厳密なチェックを行いたい場合、「JSON Schema」という仕組みを使います。これは「JSON のための設計図」のようなものです。

例えば、「age は必ず数値で、0以上でなければならない」といったルールを定義できます。

{
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["age"]
}

大規模な API 開発では、このスキーマを使って自動テストを行うのが一般的です。

7. 便利ツール紹介

開発現場でよく使われるツールを紹介します。

• VSCode: 標準で JSON の整形とバリデーションに対応しています。Alt + Shift + F で一発整形できます。
• jq コマンド: ターミナル（黒い画面）で JSON を扱うための最強ツール。curl の結果を見やすくするのによく使われます。
• Online JSON Validator: Web 上でスキーマ検証ができるサイトも多数あります。

8. モディッグスツールズ版 JSON 整形ツールの強み

当サイトのツールは、以下の点で特にこだわって作られています。

1. 完全ローカル処理で安全: 入力したデータ（社外秘のログや個人情報など）が外部サーバーに送信されることは一切ありません。
2. 破損 JSON の検出精度: 「どこでエラーが起きているか」を可能な限り分かりやすく表示します。
3. バリデーション即時反映: 入力するそばからリアルタイムで構文チェックを行います。
4. Shift-JIS 対応: 古いシステムから出力された Shift-JIS の JSON も、文字化けせずに扱えるよう配慮しています（ブラウザの機能依存ですが、ペースト時のトラブルを減らす設計です）。

9. 総まとめ

JSON はシンプルですが、ルールは厳格です。

• キーは必ずダブルクォーテーションで囲む。
• 末尾のカンマはつけない。
• コメントは書かない。
• 困ったらツールで整形＆バリデーション！

これらのポイントを押さえて、快適な JSON ライフを送りましょう。

よくある質問 (FAQ)

【付録】やってはいけない JSON の書き方一覧