JSON完全ガイド｜基礎からAPI連携・設計原則・エラー解決まで

3分でわかるJSONとは？Webエンジニアが知るべき基本とAPI連携の全知識

API連携で、「なぜか動かない…」そんな経験、ありませんか？Web開発に欠かせないJSONは、そのシンプルさゆえに、正しい使い方を深く理解していないと予期せぬエラーを招くことがあります。

この記事では、そんな日々の開発で直面するであろう、JSONの基礎知識から具体的な解決策まで、私たち開発者仲間が知っておくべきポイントを解説します。特に、エラー解決方法やTypeScript・Javaでの正しい型定義、そして保守性を高めるための設計原則に焦点を当てます。この記事を通じて、JSONを扱う自信をつけ、よりスムーズな開発を目指しましょう。

JSONとは？「データ交換フォーマット」の基本

JSON（JavaScript Object Notation）は、人間が読んで理解しやすいテキストベースのデータ交換フォーマットです。Webアプリケーションとサーバー間のAPI通信で、データをやり取りする際に最も広く使われています。

その最大のメリットは、シンプルさと軽量性です。XMLやCSVと比べて余分な情報が少なく、通信量を抑えられます。また、JavaScriptのオブジェクト記法を基にしているため、JavaScriptとの親和性が非常に高いのも特徴です。

用語解説：JSON（JavaScript Object Notation）
テキストベースのデータ交換フォーマットです。キーはダブルクォーテーションで囲み、オブジェクト（中括弧）と配列（角括弧）で階層構造を表現します。APIのレスポンスや設定ファイルで広く使われます。

JSONの基本ルール：たったこれだけ覚えればOK

JSONの構文は、たった3つの基本ルールで成り立っています。

キーと値のペア：すべてのデータは、"キー": "値"のペアで表現されます。キーは必ずダブルクォーテーション（"）で囲みます。
オブジェクト：複数のキーと値のペアをまとめる際は、中括弧（{}）を使います。
配列：複数の値をリストとして扱う際は、角括弧（[]）を使います。

日常例え：買い物リストと冷蔵庫でJSONを理解する

買い物リストと冷蔵庫でJSONを理解するイラスト — 図：買い物リストと冷蔵庫でJSONの構造を例えたイラスト

JSONを日常に置き換えるとイメージしやすくなります。例えば、冷蔵庫を1つのオブジェクト（箱）と考え、箱の中に入っている食品の一覧を配列（リスト）で表現します。キーはラベル（例：owner、items）、値はラベルに書かれた中身です。

{
  "fridge": {
    "owner": "花子",
    "items": [
      { "name": "牛乳", "count": 1 },
      { "name": "卵", "count": 6 },
      { "name": "りんご", "count": 4 }
    ]
  },
  "shoppingList": ["牛乳", "パン", "バナナ"]
}

この例での対応：

オブジェクト（{“{“}…{“}””}）＝冷蔵庫、箱、あるいはメニュー全体
キー＝ラベル（owner、items、shoppingList）
配列（[ … ]）＝複数のアイテムが並ぶ買い物リストや食品の一覧
値＝実際の中身（文字列、数値、ネストしたオブジェクトなど）

このように日常の「箱とラベル、リスト」の考え方で見ると、JSONの構造が直感的に理解できます。

JSONの特定プロパティを入れる・取り出す

簡易的なJSオブジェクト変数を使った最小例です。

// 初期データを変数で保持（JSON相当のオブジェクト）
let user = { id: 1, name: "佐藤 大輔", age: 28 };

// 特定プロパティを更新（例：age を変更）
user.age = 29; // ここで特定プロパティに値を入れる

// 特定プロパティを取り出す（例：name）
const name = user.name;
console.log("名前:", name);
console.log("名前:", name);

（fetchでのAPI取得やCORSの扱いについてはJavaScriptのAjax完全入門｜fetchの使い方・CORSエラーの対処・非同期通信の基本を解説をご参照ください）

JSONとXML・CSVの違い：エンジニアなら知るべき3つの比較ポイント

JSONがXMLやCSVよりも現代のWeb開発で主流になった理由を、3つの観点から比較してみましょう。

比較項目	JSON	XML	CSV
可読性	高い	低い（タグが多く複雑）	高い（単純な表形式）
データ構造	複雑な階層構造を表現可能	複雑な階層構造を表現可能	シンプルな表形式のみ
通信量	軽量	重い	最も軽量

結論として、JSONは人間とコンピューターのどちらにとっても「扱いやすい」バランスの取れたフォーマットです。複雑なデータを階層的に扱える柔軟性と、軽量でシンプルな構文が、現代のWeb API開発に適しています。

✅【実務で活かす】WebエンジニアがハマりがちなJSONの落とし穴

ここでは、日々の業務で私たちが直面するであろう、具体的なJSONのエラーと解決策を解説します。単なる構文ミスではなく、設計思想が原因で起きる問題に焦点を当てます。

Case1：any型で型安全性を失うTypeScriptのケース

any型は、一見便利に見えますが、後々の予期せぬバグを生み出す典型的なアンチパターンです。

用語解説：any型（TypeScript）
どんな値でも許容する特殊な型です。型チェックを回避できるため一時的には便利ですが、長期的には型安全性を損ないバグの原因になります。可能な限り具体的な型定義やユーティリティ型を使いましょう。

// ダメな例：any型でAPIレスポンスを受け取る
async function fetchUserData(userId: number): Promise<any> {
  const response = await fetch(`/api/users/${userId}`);
  const data = await response.json();
  // `data`の中身が不明なため、どこかでエラーが発生する可能性がある
  return data;
}

（TypeScriptの基本的な型設計や型の違いについてはTypeScriptとは？JavaScriptとの違いを初心者向けにわかりやすく解説をご参照ください）

any型を使うと、コンパイル時に型の安全性が失われ、ランタイム時に初めてエラーが発覚します。これを防ぐには、受け取るJSONのスキーマを正確に型定義することが不可欠です。

// 良い例：型を正確に定義し、安全性を高める
interface UserData {
  id: number;
  name: string;
  email: string;
}

async function fetchUserData(userId: number): Promise<UserData> {
  const response = await fetch(`/api/users/${userId}`);
  const data: UserData = await response.json(); // 型アサーションで安全性を保証
  return data;
}

Case2：フィールド名不一致でパースエラーが出るJavaのケース

JavaにおけるAPI連携でHttpMessageNotReadableExceptionなどのエラーに遭遇することがあります。これは、JavaのDTO（Data Transfer Object）と、受け取ったJSONのキー名が一致していない場合に発生します。

用語解説：DTO（Data Transfer Object）
システム間でデータを受け渡すための単純なオブジェクトです。受け取るJSONの構造とフィールド名が一致していないとマッピングエラーになるため、アノテーションで名前を指定することがあります。

// ダメな例
JSON: {"user_name": "daisuke"}
Java DTO:
  private String userName;

この場合、キー名がuser_name（スネークケース）とuserName（キャメルケース）で一致せず、パースエラーが発生します。

解決策
Javaでは、@JsonPropertyアノテーションを使うことで、JSONのキー名とDTOのフィールド名をマッピングできます。

// 良い例
import com.fasterxml.jackson.annotation.JsonProperty;

public class UserDto {
  @JsonProperty("user_name")
  private String userName;

  // getter, setter ...
}

（Spring Bootでのパラメータ受け取りや@RequestBodyの扱いについてはSpring Boot のパラメータ受け取り｜@ModelAttribute と @RequestBody の違いと使い分けをご参照ください）

「動く」から「美しい」へ！保守性を高めるJSON設計の原則

単にエラーを解決するだけでなく、より良い設計をすることで、将来的なバグを未然に防ぐことができます。

JSON設計の鍵は「再利用性」と「予測可能性」

JSONを設計する際は、以下の2つの原則を意識しましょう。

再利用性：同じデータ構造は、できるだけ使い回せるように設計します。例えば、{"user": {"id": 1, ...}}という構造が複数箇所で使われる場合、Userという共通のオブジェクトとして定義し、再利用性を高めます。
予測可能性：APIレスポンスの構造は、受け取る側が「次に何が来るか」を予測できるように設計します。例えば、{"data": [...], "meta": {...}}といった標準的なラッパ構造を使うことで、他のエンジニアも直感的に理解できます。

失敗しないためのJSON設計チェックリスト

開発を始める前に、このチェックリストをチームで共有し、設計ミスを防ぎましょう。

命名規則：camelCaseかsnake_caseか、プロジェクト内で統一されていますか？
必須/任意：各キーが必須なのか、任意なのかが明確ですか？（例："user_id"は必須だが、"phone_number"は任意など）
データ型：numberかstringか、厳密に定義されていますか？特に日付や数値は、意図しない型として扱われるとエラーの原因になります。

まとめ：JSONを制する者がAPI開発を制する

この記事では、「JSONとは」という基礎から、Webエンジニアが直面する具体的なエラー事例、そして保守性を高めるための設計原則までを解説しました。

JSONは単なるデータフォーマットではありません。

正しい構文を知ることで、目の前のエラーは解決できます。
設計思想を理解することで、将来的なバグを防ぎ、より美しいコードを書けるようになります。

JSONの知識を深めることは、あなたのエンジニアとしての市場価値を上げ、より裁量権のある案件や、チームを主導するポジションへの道を開きます。ぜひ、まずは手元のプロジェクトで動かしてみてください。

用語解説（まとめ）：API / スキーマ / パース
API：システムやサービスが外部に提供する機能の窓口。 スキーマ：データの形（型や必須/任意）を定義したもの。 パース：テキスト（例：JSON）をプログラムのデータ構造に変換する処理。

FAQセクション

Q. JSONのデータ型に使えるものは何ですか？
A. string、number、boolean、object、array、nullの6種類が使えます。undefinedや関数は使えません。
Q. JSONを扱うための便利なライブラリはありますか？（Java/TypeScript）
A. JavaではJacksonやGson、TypeScriptではzodやio-tsが有名です。これらのライブラリを使うことで、型安全なJSONパースが容易になります。
Q. JSONはセキュリティ上の問題がありますか？
A. 信頼できないソースからのJSONをパースする際は、悪意のあるコードが含まれていないか注意が必要です。特にeval()などを使うと脆弱性につながるため、JSON.parse()を使うべきです。