JSON の整形と検証：壊さずに扱う方法

JSON はシンプルに見えますが、カンマが1つ足りないだけでデプロイが失敗します。JSON のエラーはほとんどが複雑なものではなく、末尾のカンマ、シングルクォート、コメント、対応していない括弧のいずれかです。この記事では、有効な JSON が許す範囲、よく遭遇するエラー、そしてペイロードを確実に整形・検証する方法を説明します。

有効な JSON が許すもの

JSON の文法はとても小さいものです。

値はオブジェクト、配列、文字列、数値、true、false、null のいずれか。
オブジェクトのキーはダブルクォートで囲んだ文字列でなければならない。
文字列はダブルクォートを使う。シングルクォートは無効。
配列とオブジェクトに末尾のカンマは使えない。
コメントは JSON の仕様に含まれない。
数値は NaN、Infinity、16 進表記にはできない。

基本的にはこれだけです。厳格さこそが要点で、どの言語の JSON パーサーでも同じ入力に対して同じ結果が得られます。

よく遭遇する5つのエラー

1. 末尾のカンマ

{
  "name": "Ada",
  "age": 36,
}

これは JavaScript や JSON5 では有効ですが、JSON では無効です。最後のプロパティの後ろにあるカンマを削除してください。

2. シングルクォート

{ 'name': 'Ada' }

JSON はダブルクォートしか受け付けません。Python や JavaScript から手でコピーしたときによく起こります。

3. 引用符のないキー

{ name: "Ada" }

オブジェクトのキーはダブルクォートで囲んだ文字列である必要があります。これも JavaScript の習慣で、JSON には当てはまりません。

4. コメント

{
  // the user's name
  "name": "Ada"
}

JSON にコメントはありません。設定ファイルにコメントが必要なら JSONC や YAML を使い、JSON API にはコメントを送らないでください。

5. 括弧の不一致

} や ] の欠落は、実際の誤りの位置ではなくファイルの末尾でエラーになることがよくあります。文書を整形すると、足りない階層がはるかに見つけやすくなります。

整形が重要な理由

最小化された JSON は機械には効率的ですが、人間には読みにくいものです。整形された文書は次の利点があります。

構造が一目で分かる。
コードレビューで差分が読みやすい。
足りない括弧やカンマを見つけやすい。
2つのペイロードを比較するための安定した形になる。

API のレスポンスをデバッグするときは、読む前にフォーマッターに貼り付けてください。2つのバージョンを比較するときは、両方を先に整形してから差分を取ります。整形によって空白のノイズが消え、本当の変更が見えるようになります。

整形と最小化の使い分け

整形（プリティプリント）は読みやすさのためにインデントと改行を加えます。最小化は転送のために任意の空白を取り除きます。データとしては同じなので、読み手に合わせて選びます。

ログ、ドキュメント、テストデータ、デバッグには整形を使う。
バイト数が重要なリクエストボディやレスポンスには最小化を使う。

フォーマッターは、値を変えずに 2 スペース、4 スペース、タブ、最小化を切り替えられるべきです。

行番号でエラーを見つける

最も役立つエラーメッセージは「invalid JSON」ではなく「unexpected token at line 4, column 3」です。最近のパーサーはたいてい位置を返しますが、メッセージの形式は実行環境によって異なります。

ブラウザベースのフォーマッターなら、文書を解析して行と列を報告し、JSON が有効になるまで出力を空に保てます。このフィードバックの速さは、どの括弧が足りないかを推測するよりはるかに優れています。

JSON 整形・検証ツールはまさにそれを行います。ペイロードを貼り付けてエラー位置を確認し、解析が通ったら整形または最小化できます。すべてローカルで動くので、本番のペイロードでも安心して使えます。

JSON は JavaScript のオブジェクトではない

JavaScript のオブジェクトリテラルには、関数、undefined、シングルクォートのキー、コメントを含められます。JSON にはできません。構文が似ているため混同されがちですが、JSON はデータ形式であり、言語ではありません。

JSON を JavaScript の値にしたいときは JSON.parse が担当します。JavaScript のオブジェクトを JSON にしたいとき、JSON.stringify は次のように動作します。

undefined と関数は取り除かれる。
日付は文字列に変換される。
循環参照では例外が投げられる。
NaN と Infinity は null になる。

これらの規則を知っておくと、「なぜこのフィールドが消えたのか」という類のバグをまとめて防げます。

JSON から他の形式へ

ペイロードが有効になったら、別の形で必要になることがよくあります。

JSON → CSV はオブジェクトの配列を表計算ソフトで開ける形にします。
YAML → JSON は設定を2つの形式の間で移します。
テキスト差分チェッカーは整形後の新旧ペイロードを比較します。

実務チェックリスト

ペイロードをフォーマッターに貼り、まず構文エラーを直す。
比較する前に両方のバージョンを整形する。
最小化はデータを送る直前にだけ行う。
JSON にコメントを入れない。コメントが必要な設定には YAML か JSONC を使う。
ログに出せない秘密情報を JSON に入れない。

JSON が厳格なのは意図的です。少数の規則を覚えてしまえば、パーサーのエラーのほとんどは数秒で明白になります。