すべての開発者が知っておくべきJSONフォーマットのベストプラクティス

JSON構造の基本

JSON（JavaScript Object Notation）は、構造化されたデータを表現するための軽量テキスト形式です。その名前に反して言語非依存であり、REST APIから設定ファイルまであらゆる場所で使われています。有効なJSONドキュメントは、オブジェクト（波括弧で囲まれたキーと値のペアのセット）か配列（角括弧で囲まれた順序付きリスト）のいずれかです。

JSONの6つの値の型は: 文字列、数値、真偽値（true/false）、null、オブジェクト、配列です。JSONオブジェクトのすべてのキーは、ダブルクォートで囲んだ文字列でなければなりません——シングルクォートや引用符なしの識別子は使えません。

よくある構文エラー

JSONは厳格です。構文エラーが1つあるだけで、ドキュメント全体がパースできなくなります。最もよくある間違いは:

• 末尾カンマ: {"name": "Alice",} — 最後の要素の後の末尾カンマはJSONでは無効です（JavaScriptでは有効なため、混同されがちです）。
• シングルクォートの文字列: JSONはダブルクォートを要求します。{'key': 'value'}は有効なJSONではありません。
• 引用符なしのキー: {name: "Alice"}はJavaScriptのオブジェクトリテラル構文であり、JSONではありません。
• コメント: JSONはコメントをサポートしません。設定ファイルにコメントが必要な場合は、JSONCやYAMLを検討してください。
• undefinedとNaN: これらのJavaScript値はJSONに存在しません。nullを使うか、フィールドを省略してください。
• エスケープされていない制御文字: 文字列内の改行は、リテラルの改行ではなく\nと書かなければなりません。

読みやすいフォーマット

ネットワークで送信されるJSONは、ペイロードサイズを削減するために圧縮（ミニファイ）——空白を除去——されることが多いです。しかし、設定ファイルに保存されたり、バージョン管理にコミットされたりするJSONは、人間が読みやすいようにフォーマットすべきです。標準的な規約は:

• インデントレベルごとにスペース2つまたは4つ（一方を選んで一貫性を保つ）
• オブジェクトの各キーと値のペアを1行に
• 開き波括弧は親キーと同じ行に、閉じ波括弧は独立した行に
• シンプルな値の配列は短ければ1行にまとめても構わない

ほとんどのエディタはJSONを自動フォーマットできます。VS Codeでは、右クリックして「ドキュメントのフォーマット」を選ぶか、ショートカットShift+Alt+Fを使います。コマンドラインユーザーはjq . input.jsonを使って任意のJSONファイルを整形できます。

命名規則

JSON自体は命名規則を強制しませんが、APIやコードベースでひとつを選んで一貫性を保つべきです。3つの一般的なパターンは:

• キャメルケース（firstName）— JavaScriptのAPIやほとんどのRESTサービスの標準
• スネークケース（first_name）— PythonのAPIやPostgreSQLで一般的
• パスカルケース（FirstName）— 一部の.NETやC#環境で使用

単一のAPIで規則を混在させると混乱の原因になります。ある規則のAPIを使いながら、自分のコードベースは別の規則を使っている場合、コード全体にその場しのぎの変換を散らばらせるのではなく、専用のシリアライゼーションレイヤーで変換を処理してください。

nullと存在しないフィールドの扱い

JSONオブジェクトで値の不在を表す方法は2つあります: キーが存在して値がnullであるか、キー自体が存在しないかです。これらは異なるセマンティクスを持ちます。フィールドが期待されるが値がない場合（例: ユーザーが空欄にした中間名フィールド）はnullを使います。そのレコードに全く該当しない場合はフィールド自体を省略します。APIのコンシューマーが期待できるよう、自分のAPI内で一貫したアプローチを決めてください。

大きな数値と精度

JSONの数値には定義上のサイズ制限はありませんが、多くのパーサーはIEEE 754の倍精度浮動小数点値としてデシリアライズします。これは2^53より大きな整数を正確に表現できないことを意味します。JSONが大きな整数（データベースID、通貨の最小単位での金額、暗号識別子など）を運ぶ必要がある場合は、それらを文字列として表現し、APIにドキュメント化してください。これはTwitterのツイートIDでよく知られた落とし穴です。

JSONの検証

構文検証（これは有効なJSONか？）を超えて、JSON Schemaはドキュメントの期待される構造を定義できます: どのフィールドが必須か、その型、値の範囲など。ajv（JavaScript）、jsonschema（Python）、オンラインバリデータなどのツールで、JSONドキュメントをスキーマに対して検証できます。本番環境で公開または使用するAPIには、境界でのJSON Schema検証を実装する価値があります。

TheDailyUtilsのようなJSONフォーマッター・バリデーターは、見慣れないペイロードの構文エラーを最速でキャッチする方法です。生のJSONを貼り付けるだけで、パースが通るかどうか、エラーがどこにあるかが即座にわかります。

JSONを即座に整形・検証する

無料のJSONフォーマッターを開く — 任意のJSONを貼り付けて、整形、圧縮、または構文エラーを数秒でキャッチ。ブラウザ上で動作し、データはプライベートに保たれます。