アイキャッチ画像: 画面に表示された色とりどりのソースコード。写真提供: Markus Spiske on Pexels(無料利用可)

開発者なら誰でもあの光景を知っています。数千文字のワンライナーJSON。バグは括弧の不一致と見えない末尾カンマの間に潜んでいる。JSONはWebの標準データ形式——API、設定ファイル、ログ、そして今やLLMの関数呼び出しまで、すべてがJSONを話します。それにもかかわらず、デバッグ時間の不釣り合いな部分を占め続けているのは、「簡単に見える」からです。

本ガイドでは、JSONの基本、時間を最も浪費する構文エラー、整形・圧縮・検証の規律あるワークフローを解説します。当サイトの無料JSONフォーマッター/バリデーターは完全にブラウザ内で動作します——貼り付ければ、ワンクリックで整形・圧縮・検証が完了します。

1分でわかるJSON

JSON(JavaScript Object Notation)は構造化データのためのテキスト形式です。値の型は6つだけ。オブジェクト {}、配列 []、文字列、数値、真偽値、null。これが言語のすべてです。コメントも変数もロジックもないことがJSONの強みで、機械にとって曖昧さがなく、(整形すれば)人間にとっても読みやすくなります。

このミニマリズムこそが罠でもあります。JSONはJavaScriptより厳格で、「JSONのエラー」の大半はJavaScriptの癖の持ち込みです。頻繁に破られる3つの構文ルール:

  1. キーは二重引用符で囲む。 {name: "AI"} はJavaScriptオブジェクトであってJSONではない
  2. 文字列は二重引用符。 {'a': 1} は不正——JSONにシングルクォートは存在しない
  3. 末尾カンマ禁止。 [1, 2, 3,] も {"a": 1,} も不正

デバッグ時間を最も浪費する5つのエラー

1. 末尾カンマ。 手書きJSONで最も多いエラーであり、文字列連結で組み立てたAPIペイロードで最も厄介です。対処は機械的です——整形して、全配列・全オブジェクトの最後の要素を目視する。

2. 引用符と制御文字のエスケープ漏れ。 文字列内の " は \" に、文字列内の改行は \n にする必要があります。HTMLからスクレイピングしたデータやWordからコピーしたテキストはこのルールを頻繁に破ります。

3. コメントの持ち込み。 JSONにコメントはありません。JavaScriptの設定ファイルからコピーした // や /* */ はパースエラーになります。コメントが必要ならJSONC(VS Codeが使うコメント付きJSON)を使いますが、標準パーサーは拒否することを覚えておいてください。

4. 数値形式の違反。 先頭ゼロ(01)、末尾の小数点(1.)、16進数、NaN/Infinity はすべて不正です。スプレッドシート由来の数値文字列は先頭ゼロを含みがちです。

5. BOMと見えない文字。 ファイル先頭のUTF-8バイトオーダーマーク(U+FEFF)や、チャットアプリから貼り付けたゼロ幅スペースは、一見空の行で「unexpected token」という狂わせるエラーを引き起こします。

この5つはすべて、JSONフォーマッターのバリデーターがブラウザ標準の JSON.parse で即座に検出し、正確なエラー位置を報告します。

エラーを防ぐ整形ワークフロー

整形は見た目の問題ではありません。プリティプリントは4,000文字のワンライナーを読めるツリーに変え、「読むこと」こそがエラーを本番前に発見する手段です。ワークフローは次のとおり:

  1. まず整形。 2または4スペースでインデント。ワンライナーのまま診断しない——視覚構造はデバッグの一部です
  2. 検証。 パースできることを確認。失敗時はエラーメッセージに位置が含まれます
  3. 差分。 APIレスポンスを比較するときは両方を圧縮してからdiffする。空白やキー順の差が消えます
  4. 送信前に圧縮。 圧縮済みペイロードは小さく、帯域が減り、従量課金のAPIでは請求トークンも減ります。ほぼすべてのLLM API呼び出しの本文はJSONであり、圧縮したリクエストはプリティプリントより20〜30%小さくなります

AI時代にJSONがさらに重要な理由

JSONはAIアプリケーション開発の周辺から中心へ移動しました。いま支配している3つの場所:

チャットAPI。 OpenAI互換エンドポイントは {"messages": [...]} 配列を送受信します。すべてのリクエスト本文とレスポンスがJSONであり、不正な本文はレート制限以外で呼び出しが失敗する最も一般的な原因です。

関数呼び出し。 LLMがツールを呼ぶとき、引数はコードがパースするJSONオブジェクトとして届きます。末尾カンマ付きの {"city": "Tokyo",} を出力するモデルは厳格なパーサーをクラッシュさせます——有効なJSONを保証する構造化出力モードが本番統合のデフォルトになった理由の一つです。

構造化出力。 JSON Schemaによる制約付き生成は、モデルに有効なドキュメントだけを出力させます。ただしスキーマ自体もJSONであり、200行のスキーマの構文エラーはリクエスト本文のエラーと同じく致命的です。

実用的な組み合わせ:JSONツールでペイロードを整形・検証し、トークン・コスト計算機で実行コストを見積もる。この2つでAPI呼び出しのライフサイクル全体——構築、検証、価格——がカバーできます。

JSONと代替形式の使い分け

  • JSON — APIと設定のデフォルト。特別な理由がなければこれを使う
  • JSONL(JSON Lines) — 1行1JSONオブジェクト。OpenAIのバッチファイルやストリーミングデータセットの形式
  • YAML — 人が書く設定(Ansible、CIパイプライン)。コメント可だが空白に敏感
  • TOML — Rust・Go・Hugoの設定形式(当サイトの設定もTOML)。フラットな設定ではYAMLよりシンプル
  • Protobuf/MessagePack — 解析速度が可読性を上回る高スループット内部サービスのバイナリ形式

共通点:すべて構造化されており、JSONで培ったデバッグスキルはそのまま他に応用できます。

エディタ整形とオンラインツールの使い分け

ブラウザツールが常に必要なわけではありません。主要な環境にはすべてフォーマッターが内蔵されており、4つの選択肢を知っていれば状況に応じて最速のものを選べます:

  • VS Code: .json ファイルを開いて「ドキュメントのフォーマット」(macOSは Shift+Option+F、Windowsは Shift+Alt+F)。組み込みのJSON言語モードが整形し、構文エラーを行内表示します。JSONがすでにファイルになっている場合の最速手段です。
  • jq: コマンドラインの万能ナイフ。echo '{"a":1}' | jq . で整形、jq -c . で圧縮。さらにjqは不正なJSONのパースを拒否するため、バリデーターを兼ねます。シェルパイプラインやログの追尾に必須です。
  • Python: python3 -m json.tool file.json で標準出力に整形。Pythonがある環境ならインストール不要で使えます。
  • ブラウザツール: JSONがチャットやメール、チケットで届く場合の正解。貼り付けてワンクリックで完了。AI ForwardのJSONフォーマッター/バリデーターはこのケースをカバーし、正確なエラー位置付きの検証も提供します。

エディタのフォーマッターが通常提供しないものは、正確なエラーメッセージです。多くは行を下線表示するだけ。ドキュメントが深く壊れている場合は、正確な文字位置を報告するバリデーターに通してから修正に取りかかりましょう。

HTTP層のJSON:ヘッダーとレスポンス

整形はHTTP層でも重要で、APIデバッグ時間の大半は2つのヘッダーミスに費やされています:

1. Content-Type の誤り。 JSONボディは application/json(任意で ; charset=utf-8)で送る必要があります。ブラウザのデフォルトである application/x-www-form-urlencoded で送ると、サーバー側のパース失敗か、黙った誤解釈が起きます。典型的な症状:サーバーがあなたのJSONを単一の文字列フィールドとして受け取る。

2. Accept ヘッダーの欠落。 Accept: application/json を送らないクライアントは、JSONエラーボディの代わりにHTMLエラーページを受け取り、下流のレスポンスパーサーを壊します。行儀の良いAPIは機械可読なエラー——RFC 7807の application/problem+json——を返しますが、要求されたときだけです。

API作業のための2つの習慣:

  • 圧縮してからミニファイ。 圧縮済みJSONはプリティプリントより良くgzipされます。大きなペイロードはまず圧縮し、サーバーの Content-Encoding: gzip に残りを任せます。従量課金のLLM APIでは、ボディが小さいほど請求トークンも減ります。
  • レスポンスのパースは信用しない。 JSONを正規表現や文字列スライスで手動パースせず、常にプラットフォームの JSON.parse 相当を使い、エラーハンドリングで包みます。レスポンスストリームに紛れた500文字のエラーページは、ワーカーをクラッシュさせるのではなく、クリーンなログメッセージを残すべきです。

フォーマッターで速くなる3つのワークフロー

ログ。 現代のサービスはJSON Lines——1行1構造化オブジェクト——でログを出力します。標準ツールは jq です。ログファイルをtailし、jq 'select(.level == "error")' にパイプすれば、ノイズが消えます。同じJSONLの知識は、同一の1行1オブジェクト形式を使うLLMバッチファイルにもそのまま応用できます。

設定ファイル。 package.json、settings.json、tsconfig.json は常に手で編集されます。フォーマッターは新しいエントリを追加した瞬間の末尾カンマを捉え、バリデーターは壊した瞬間を捉えます。注意:VS Codeの settings.json はJSONC(コメント可)であり、コメントを含むと厳格なJSONツールでの整形は失敗します——それ自体が「いま編集しているのはどの形式か」を知る有用なシグナルです。

LLMペイロード。 チャット補完リクエストはJSON、関数呼び出しの引数はJSON、JSON Schemaの出力制約もJSON。送信前に検証し、コストを測る前に圧縮する——トークン・コスト計算機は送ったものをそのまま測るので、圧縮されたJSONの方が低く出ます。2つのツールを組み合わせれば、「JSONの問題」から「解決済みの問題」への最短経路になります。

JSON Schema:検証から構造化出力へ

ここまでは「手で確認するドキュメント」としてJSONを扱ってきました。産業強度のアップグレードが JSON Schema です——別のJSONドキュメントがどうあるべきかを形式的に記述したJSONドキュメント。スキーマがあれば、バリデーターはペイロードが正しいかをミリ秒で判定でき、さらにLLMを「正しいペイロードだけを出力するよう」制約することも可能になっています。

最小のスキーマ:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "tags": { "type": "array", "items": { "type": "string" } },
    "active": { "type": "boolean" }
  },
  "required": ["name", "active"],
  "additionalProperties": false
}

このスキーマが言っているのは:空でない name 文字列、文字列の配列 tags、真偽値 active を持つオブジェクト——それ以外は許さない。ツールはJavaScriptの ajv、Pythonの jsonschema、OpenAPIツールチェーン内蔵の検証など。スキーマの役割は3つ:

  1. 契約の文書化。 スキーマはAPIの期待値の実行可能なドキュメントであり、同じファイルが検証・コード生成・テストを駆動します
  2. 境界での早期失敗。 取り込み時に検証すれば、下流の全コンポーネントは整形式データを前提にでき、再チェックが不要になります
  3. LLM出力の制約。 OpenAIの構造化出力モードはJSON Schemaを受け取り、モデルの応答がスキーマに対してパースできることを保証します。DeepSeekなどもスキーマ対応のJSONモードを提供しています。本番の関数呼び出しでは、スキーマ制約付き出力はベストプラクティスからデフォルトになりました——「モデルがパース不能なものを返した」という問題を、予期される失敗から設定エラーに変えてくれます

デバッグ時間を節約するスキーマ設計のコツ:可能ならスキーマを小さくフラットに保つ。ステータスフィールドは自由文字列より enum を選ぶ。そして必ず additionalProperties: false を設定する——寛容なチェックを本物の契約に変えるのはこのフラグ1つです。スキーマが大きくなったら、まずスキーマ自体をフォーマッターで検証しましょう。末尾カンマを含む200行のスキーマの失敗はモデルのエラーと見分けがつきませんが、JSONフォーマッターなら本当の原因をワンクリックで特定できます。

JSONの意外な落とし穴:誰もが一度はハマる仕様

JSONは見かけほど単純ではありません。仕様由来の癖のうち、実務で当たる4つ:

数値の精度。 JSONの数値はIEEE 754倍精度浮動小数点数で解釈されることが多く、64ビット整数(Snowflake IDなど)は丸め誤差で壊れます。典型的な症状:IDが 9223372036854775807 から 9223372036854776000 になる。対策は、精度が必要な数値は文字列で運ぶこと。TwitterがIDを文字列にした理由と同じです。

重複キー。 {"a": 1, "a": 2} は仕様上「許容されるが、どちらの値が採用されるかは処理系依存」です。多くのパーサーは最後の値を黙って採用します。手動マージで生成されたペイロードで最も発生しやすいバグで、検証では発見できません(構文的には正しいため)。整形して目視するのが実質唯一の対策です。

キーの順序。 オブジェクトのキー順に意味はありません。ログのdiffを取るときに順序で偽の差分が出ないよう、比較前にソートするか、jqの -S(キーソート)を使いましょう。

文字列と文字列の違い。 二重引用符の文字列しかJSONにはありません。シングルクォート、テンプレートリテラル、末尾の見えない空白——全部「JSの癖」由来のエラーです。エラーが出たらまず引用符を疑う、と覚えておけばデバッグが速くなります。

JSONデバッグの実演:ステップバイステップ

理論は安い。実在しそうな失敗で全体の流れを示します。サポートチケットには「連携が止まった」とあり、ペイロードはスクリプトの文字列連結で組み立てられたもの:

{"user": "O'Brien", "plan": "pro", "features": ["sso", "audit-log",]}

バグは2つあります——エスケープされていない引用符と末尾カンマ——そして失敗する段階が違います。規律ある手順:

  1. まず検証。 JSONフォーマッター/バリデーターに貼り付けます。パーサーは features 配列の末尾カンマを正確な位置付きで報告します(二重引用符で囲まれたJSONでは "O'Brien" のアポストロフィは実は合法です——エラーの正体は末尾カンマです)
  2. 整形。 カンマを削除してプリティプリント。ネスト構造が見え、文字列連結で途中が切れたペイロードなら、ここでオブジェクトが閉じていないことが見えます
  3. 期待スキーマとdiff。 整形済みペイロードをドキュメントの例と比較。バリデーターには検出できないキー名の間違い(featurs など)がここで見つかります
  4. 圧縮して送信。 修正済みペイロードを圧縮してAPIへ——そしてトークン・コスト計算機が正直に価格を出せます

このパターンはすべてのJSONインシデントに一般化できます:検証で構文エラーを見つけ、整形で構造を見て、diffで意味論エラーを見つけ、圧縮して送る。4ステップ、それぞれ1つのツール、推測はゼロ。

よくある質問


ツールの動作はECMAScriptのJSON.parse仕様に基づき検証済み。JSONL・JSONC・TOMLの説明は2026年11月時点の公開仕様に基づきます。