API レスポンスを貼り付けたら、赤い一行に Unexpected token。どこが悪いのか目で追ううちに、結局は括弧をひとつずつ数えている。JSON はルールが単純なのに、その単純さゆえに小さなミスひとつが全体のパースを止めます。まずは、どこが壊れているかを見つける方法から整理します。
壊れた JSON、まずはどこが問題か
JSON パーサーは最初のエラーで止まり、その位置を教えてくれます。メッセージはつい読み飛ばしがちですが、そこに行と列が入っています。
たとえば { "name": "PiPi", "role": "editor", } のように最後の値の後にカンマを残すと、パーサーは Expected double-quoted property name in JSON at position 40 (line 4 column 1) と答えます。PiPi Worlds の JSON フォーマッターはこの行・列をそのまま指し示すので、閉じ括弧のある4行目へ直行すればよいのです。犯人はその直前の末尾カンマです。
よく出るエラーは決まっています。
| エラー | 症状 |
|---|---|
| 末尾カンマ | 最後の要素の後の余分なカンマ |
| クォート抜け | キーや文字列をダブルクォートで囲んでいない |
| 括弧の不一致 | {・[ を閉じていない |
| コロン抜け | キーと値の間の : がない |
JSON はシングルクォート・コメント・末尾カンマを許可しません(RFC 8259)。JavaScript のオブジェクトリテラルと混同して起きるミスが多いです。
見やすく整形するか、一行に圧縮するか
有効な JSON なら、インデントを付けて構造を一目で確認できます。2スペース・4スペース・タブから、チームの規約に合うものを選べます。
逆に転送サイズを抑えたいときは、圧縮ですべての空白を取り除きます。{ "a": 1, "b": [1, 2, 3] } は {"a":1,"b":[1,2,3]} の一行になります。同じデータを表示用と転送用で行き来する作業なので、出番は多いです。
キー整列: 2つの API レスポンスを行単位で比較する
あまり知られていませんが、デバッグで強力なのがキー整列です。オブジェクトのキーをアルファベット順に並べ替えます。
2台のサーバーが同じデータを返すのに、キーの順序だけが違って diff が真っ赤になった経験はありませんか。両方をキー整列でそろえると、順序の差は消えて、本当に異なる値だけが残ります。たとえば {"name":"PiPi","id":42,"active":true} は active・id・name の順に並び替えられ、別のレスポンスと行をそろえて比較できます。
大きな数値が静かに変わる罠
これは知らないと長くハマります。JSON の数値は JavaScript で IEEE-754 倍精度としてパースされます。
問題は安全な整数の範囲を超えるときです。{"id": 12345678901234567890} を整形すると {"id": 12345678901234567000} が出てきます。下の桁が静かに 000 に変わったのです。JavaScript が安全に扱える整数は 2^53、つまり 9007199254740991 までだからです。Discord や Twitter の ID のような大きな整数は、この範囲を簡単に超えます。正確な桁が必要なら、元の JSON でその値を文字列("12345678901234567890")にしておくのが安全です。ツールに一度通せば、自分のデータにこの罠があるかすぐ見えます。
その API レスポンス、どこに貼っていますか
最後に押さえる点です。デバッグのために貼り付ける JSON には、アクセストークンや内部 ID、個人情報が混ざっていることが少なくありません。入力をサーバーへ送るオンラインフォーマッターなら、その機微なレスポンスがまるごと第三者に渡ります。
PiPi Worlds の JSON フォーマッターは、パースがすべてブラウザ内で実行されます。入力はサーバーへ送られないため、トークンを含む設定ファイルや API レスポンスも安心して整えられます。JSON の中の base64 値が気になれば Base64 ツール、その値が JWT なら JWT デコーダーへそのまま続けて確認できます。