JSONとは？書き方・データ型・APIでの使われ方を初心者向けにわかりやすく解説

Webサイトやアプリのしくみを学び始めると、かなり早い段階で「JSON」という言葉に出会います。

「JSONファイルを開いたら {} や [] が並んでいた」
「APIのレスポンスがJSONで返ってくると書いてある」
「JavaScriptのオブジェクトと何が違うの？」
「XMLとJSONはどちらを使うの？」

こうした疑問を持つ人は少なくありません。

JSONは、プログラミング初心者にとって少し記号が多く見える形式です。しかし、正体はそれほど難しいものではありません。ざっくり言えば、コンピューター同士がデータをやり取りするための、読みやすくて軽いテキスト形式です。

この記事では、JSONとは何か、基本ルール、データ型、Web APIでの使われ方、XMLとの違い、具体例までをまとめて解説します。これからWeb制作、アプリ開発、API連携、JavaScript、Pythonなどを学ぶ人でも理解しやすいように、なるべく身近な例を使って説明します。

サジェストキーワード調査から見える読者の疑問

記事作成にあたり、Googleサジェストを確認したところ、JSON関連では次のような検索候補が見られました。

メインキーワード	サジェスト例
JSON	jsonファイルとは、jsonとは、json format、json viewer、json解析、json formatter、json フォーマット
JSONとは	jsonとはわかりやすく、jsonとは読み方、jsonとは python、jsonとはなにか、jsonとは初心者
JSON 書き方	json 書き方、json 書き方配列、json 書き方複数、json 書き方初心者、json 書き方入れ子、json 書き方ルール
JSON API	json api、json api とは、json api一覧、json api sample、json api 使い方、json api rest、json api specification

この結果から、検索する人が知りたいことは大きく分けて次の5つです。

JSONとは何かを、専門用語なしで知りたい
JSONの正しい書き方やルールを知りたい
配列、入れ子、複数データの書き方を知りたい
APIでJSONがどう返ってくるのかを知りたい
XMLやJavaScriptオブジェクトとの違いを知りたい

そこで本記事では、単に「JSONはデータ形式です」と説明するだけでなく、実際に読める・書ける・APIの動きがイメージできるところまで掘り下げます。

JSONとは

JSONは、JavaScript Object Notationの略です。読み方は一般的に「ジェイソン」です。

IETFの標準仕様であるRFC 8259では、JSONは「軽量で、テキストベースで、言語に依存しないデータ交換形式」と説明されています。また、構造化データを持ち運びしやすい形で表すための小さなルールセットとして定義されています。
MDN Web Docsでも、JSONは「構造化データを文字列として表現するためのテキストベースのデータ形式」と説明されています。

簡単に言うと、JSONは次のような場面で使われるデータの書き方です。

Copy{
  "name": "佐藤花子",
  "age": 28,
  "isMember": true,
  "favoriteFoods": ["寿司", "カレー", "プリン"]
}

このデータを見ると、なんとなく意味がわかるのではないでしょうか。

name は「佐藤花子」
age は 28
isMember は true、つまり会員である
favoriteFoods は好きな食べ物の一覧

JSONは人間にもある程度読みやすく、プログラムにも扱いやすい形をしています。そのため、Web API、設定ファイル、アプリのデータ保存、サーバーとブラウザの通信などで広く使われています。

JSONは「JavaScript専用」ではない

名前にJavaScriptと入っているため、「JSONはJavaScriptでしか使えないのでは？」と思うかもしれません。

しかし、それは誤解です。

JSONはJavaScriptのオブジェクト記法に由来していますが、現在ではJavaScriptに限らず、Python、PHP、Ruby、Go、Java、C#など、さまざまな言語で扱われています。RFC 8259でも、JSONは言語に依存しない形式とされています。

たとえば、同じJSONデータをPythonで読み込めば辞書やリストのように扱えます。PHPなら連想配列やオブジェクトとして扱えます。つまりJSONは、プログラミング言語同士の「共通語」のような役割を持っています。

JSONが使われる主な場面

JSONは、見えないところで毎日のように使われています。代表的な用途を見てみましょう。

用途	具体例
Web APIのレスポンス	天気情報、ニュース一覧、商品データ、ユーザー情報などを返す
設定ファイル	アプリや開発ツールの設定を保存する
データ保存	小規模なデータやテストデータを保存する
フロントエンドとバックエンドの通信	ブラウザとサーバー間で情報をやり取りする
外部サービス連携	決済、地図、SNS、分析ツールなどと連携する

たとえば天気アプリを開いたとき、画面には「東京 28℃ 晴れ」のように表示されます。裏側では、アプリが天気APIにリクエストを送り、サーバーからJSON形式の天気データを受け取り、その中から必要な値を取り出して画面に表示していることがあります。

JSONの基本ルール

JSONには、正しく読み書きするためのルールがあります。見た目はJavaScriptのオブジェクトに似ていますが、JavaScriptの書き方がそのまま何でも使えるわけではありません。

まず、基本形は次のようになります。

Copy{
  "key": "value"
}

JSONでは、データを「キー」と「値」の組み合わせで表します。

"key"：データの名前
"value"：その中身

たとえば、商品データなら次のように書けます。

Copy{
  "id": 101,
  "name": "ワイヤレスマウス",
  "price": 2980,
  "inStock": true
}

この例では、id、name、price、inStock がキーです。それぞれに数値、文字列、真偽値が入っています。

JSONを書くときの主なルール一覧

JSONで特につまずきやすいルールを表にまとめます。

ルール	正しい例	間違った例
キーはダブルクォーテーションで囲む	`"name": "田中"`	`name: "田中"`
文字列もダブルクォーテーションで囲む	`"東京"`	`'東京'`
キーと値はコロンで区切る	`"age": 30`	`"age" = 30`
複数の項目はカンマで区切る	`"a": 1, "b": 2`	`"a": 1 "b": 2`
最後の項目にカンマを付けない	`"age": 30`	`"age": 30,`
コメントは書けない	なし	`// コメント`
`true`、`false`、`null` は小文字	`true`	`True`
`NaN` や `Infinity` は使えない	なし	`NaN`

JSONでは、キーを必ずダブルクォーテーションで囲む点が特に大切です。JavaScriptでは次のように書ける場合があります。

Copy{
  name: "田中"
}

しかし、これはJSONとしては正しくありません。JSONでは次のように書きます。

Copy{
  "name": "田中"
}

また、末尾のカンマも許可されていません。

Copy{
  "name": "田中",
  "age": 30
}

これは正しいJSONです。

一方、次は間違いです。

Copy{
  "name": "田中",
  "age": 30,
}

最後の "age": 30 の後ろにカンマがあるため、JSONとしては無効です。JavaScriptの配列やオブジェクトでは末尾カンマが許されることもありますが、JSONでは使えません。

JSONのデータ型

JSONで表現できるデータ型は限られています。RFC 8259では、JSONは4つのプリミティブ型と2つの構造化型を表せるとされています。

データ型	説明	例
文字列 string	文字のデータ	`"こんにちは"`
数値 number	整数や小数	`100`, `3.14`, `-20`
真偽値 boolean	真または偽	`true`, `false`
null	値がないことを示す	`null`
オブジェクト object	キーと値のまとまり	`{ "name": "山田" }`
配列 array	値の並び	`[1, 2, 3]`

それぞれ見ていきましょう。

文字列 string

文字列は、名前、住所、説明文、IDなどを表すときに使います。JSONでは文字列を必ずダブルクォーテーションで囲みます。

Copy{
  "name": "鈴木一郎",
  "city": "大阪市",
  "message": "ご注文ありがとうございます"
}

シングルクォーテーションは使えません。

Copy{
  "name": '鈴木一郎'
}

これはJSONとしては無効です。

数値 number

数値は、年齢、価格、個数、温度、緯度経度などに使われます。

Copy{
  "age": 35,
  "price": 1980,
  "temperature": 26.5,
  "latitude": 35.681236
}

JSONの数値には注意点があります。NaN や Infinity はJSONの数値として使えません。また、先頭に不要なゼロを置く表記も認められていません。

Copy{
  "count": 012
}

このような書き方は避けます。

真偽値 boolean

真偽値は、オン・オフ、会員かどうか、在庫があるかどうかなどを表します。

Copy{
  "isMember": true,
  "inStock": false
}

true と false は必ず小文字です。True や FALSE はJSONではありません。

null

null は「値がない」「未設定」「該当データなし」を表すときに使います。

Copy{
  "middleName": null,
  "deletedAt": null
}

たとえばユーザーのミドルネームが登録されていない場合、空文字 "" にするか null にするかは設計次第です。一般的には、「値そのものが存在しない」ことを明確にしたいときに null を使います。

GitHub REST APIのドキュメントでも、レスポンスボディは通常JSON形式で、空欄のフィールドは省略ではなく null として含まれると説明されています。

オブジェクト object

オブジェクトは、複数のキーと値をまとめる形式です。

Copy{
  "user": {
    "id": 1,
    "name": "山田太郎",
    "email": "taro@example.com"
  }
}

この例では、user の中にさらに id、name、email があります。このように、オブジェクトの中にオブジェクトを入れる構造を「入れ子」と呼びます。

ユーザー情報、商品情報、記事情報など、まとまったデータを表すときによく使われます。

配列 array

配列は、複数の値を順番に並べる形式です。

Copy{
  "colors": ["red", "green", "blue"]
}

商品一覧のように、同じ種類のデータを複数並べるときにも使います。

Copy{
  "products": [
    {
      "id": 1,
      "name": "ノート",
      "price": 180
    },
    {
      "id": 2,
      "name": "ペン",
      "price": 120
    }
  ]
}

この例では、products が配列で、その中に商品オブジェクトが2つ入っています。Web APIのレスポンスでは、このような「配列の中にオブジェクトが並ぶ形」がよく登場します。

JSONの具体例

ここで、少し実用的なJSONを見てみましょう。たとえばブログ記事のデータなら、次のように表せます。

Copy{
  "id": 501,
  "title": "JSONの基本を学ぼう",
  "author": {
    "id": 12,
    "name": "編集部"
  },
  "tags": ["JSON", "API", "Web開発"],
  "published": true,
  "publishedAt": "2026-08-11T10:00:00Z",
  "summary": "JSONの書き方やAPIでの使われ方を解説する記事です。"
}

このJSONには、さまざまなデータ型が含まれています。

キー	値	データ型
id	`501`	数値
title	`"JSONの基本を学ぼう"`	文字列
author	`{ ... }`	オブジェクト
tags	`["JSON", "API", "Web開発"]`	配列
published	`true`	真偽値
publishedAt	`"2026-08-11T10:00:00Z"`	文字列
summary	`"JSONの書き方やAPIでの使われ方を解説する記事です。"`	文字列

日付はJSON専用の日付型ではなく、文字列として扱われることが多いです。APIではISO 8601形式の日時文字列が使われるケースがよくあります。

JSONファイルとは

JSONファイルとは、JSON形式で書かれたテキストファイルです。拡張子は一般的に .json です。

例：

Copysettings.json
users.json
products.json
package.json

中身は普通のテキストなので、テキストエディタやコードエディタで開けます。MDNでも、JSON文字列は .json 拡張子のテキストファイルとして格納でき、MIMEタイプは application/json と説明されています。

設定ファイルとしてのJSONは、開発現場でよく見かけます。たとえば、JavaScriptプロジェクトでは package.json がよく使われます。ここにはプロジェクト名、バージョン、依存パッケージ、実行スクリプトなどが書かれます。

JSONとJavaScriptオブジェクトの違い

JSONはJavaScriptオブジェクトに似ています。しかし、同じものではありません。

JavaScriptのオブジェクトは、プログラムの中で使うデータ構造です。一方、JSONはデータ交換のためのテキスト形式です。

比較項目	JSON	JavaScriptオブジェクト
正体	テキスト形式	JavaScriptのデータ構造
キーの引用符	必ずダブルクォーテーション	省略できる場合がある
文字列	ダブルクォーテーションのみ	シングル、ダブル、バッククォートが使える
コメント	書けない	書ける
関数	入れられない	入れられる
undefined	使えない	使える
末尾カンマ	使えない	使える場合がある

たとえば次はJavaScriptでは使えることがあります。

Copyconst user = {
  name: "田中",
  age: 30,
  greet: function() {
    console.log("こんにちは");
  }
};

しかし、これはJSONではありません。JSONには関数を書けないからです。

JSONとして書くなら、次のようになります。

Copy{
  "name": "田中",
  "age": 30
}

JSONをプログラムで扱うときの基本

JavaScriptでは、JSONを扱うために JSON.parse() と JSON.stringify() がよく使われます。MDNでも、この2つのメソッドはJSON文字列とJavaScriptオブジェクトを相互に変換する機能として説明されています。

メソッド	役割
`JSON.parse()`	JSON文字列をJavaScriptの値に変換する
`JSON.stringify()`	JavaScriptの値をJSON文字列に変換する

たとえば、APIから返ってきたJSON文字列をJavaScriptで扱える形に変換する場合は、JSON.parse() を使います。

Copyconst text = '{"name":"田中","age":30}';
const user = JSON.parse(text);

console.log(user.name); // 田中

逆に、JavaScriptのオブジェクトをJSON文字列に変換する場合は、JSON.stringify() を使います。

Copyconst user = {
  name: "田中",
  age: 30
};

const jsonText = JSON.stringify(user);
console.log(jsonText);

出力される文字列は次のような形です。

Copy{"name":"田中","age":30}

APIの動き：JSONはこうやって返ってくる

JSONを理解するうえで、Web APIの流れを知ることは欠かせません。

APIとは、あるシステムの機能やデータを、別のプログラムから使えるようにする窓口のようなものです。Web APIでは、HTTPを使ってリクエストとレスポンスをやり取りします。

流れを単純化すると、次のようになります。

ブラウザやアプリがAPIにリクエストを送る
サーバーがリクエスト内容を確認する
サーバーがデータベースなどから必要な情報を取得する
サーバーがJSON形式のレスポンスを作る
ブラウザやアプリがJSONを受け取る
受け取ったJSONを画面表示や処理に使う

たとえば、天気情報を取得するAPIなら次のようなリクエストになります。

CopyGET /forecast?latitude=35.68&longitude=139.76 HTTP/1.1
Accept: application/json

サーバーは次のようなレスポンスを返します。

CopyHTTP/1.1 200 OK
Content-Type: application/json

Copy{
  "latitude": 35.68,
  "longitude": 139.76,
  "current": {
    "temperature_2m": 28.4,
    "relative_humidity_2m": 62,
    "weather_code": 1
  }
}

ここで重要なのは、レスポンスはJSONだけで成り立っているわけではないという点です。実際には、HTTPステータスコード、ヘッダー、ボディがあります。

要素	例	役割
ステータスコード	`200 OK`	リクエストが成功したかを示す
ヘッダー	`Content-Type: application/json`	データ形式などの追加情報
ボディ	`{ "temperature": 28.4 }`	実際のデータ本体

GitHub REST APIのドキュメントでも、リクエストにはHTTPメソッドやパス、ヘッダーなどが含まれ、レスポンスにはステータスコード、ヘッダー、必要に応じてレスポンスボディが含まれると説明されています。また、GitHub REST APIでは多くの場合、レスポンスボディはJSON形式です。

HTTPメソッドとJSONの関係

Web APIでは、操作の種類に応じてHTTPメソッドを使い分けます。

HTTPメソッド	主な用途	JSONとの関係
GET	データを取得する	JSONのレスポンスを受け取ることが多い
POST	新しいデータを作成する	JSONを送信し、結果もJSONで受け取ることがある
PATCH	一部を更新する	更新内容をJSONで送ることがある
PUT	データを置き換える	置き換え内容をJSONで送ることがある
DELETE	データを削除する	結果やエラー情報がJSONで返ることがある

たとえば、商品一覧を取得するならGETです。

CopyGET /products HTTP/1.1
Accept: application/json

レスポンス例：

Copy[
  {
    "id": 1,
    "name": "ノート",
    "price": 180
  },
  {
    "id": 2,
    "name": "ペン",
    "price": 120
  }
]

新しい商品を登録するならPOSTを使うことがあります。

CopyPOST /products HTTP/1.1
Content-Type: application/json

送信するJSON：

Copy{
  "name": "消しゴム",
  "price": 100
}

レスポンス例：

Copy{
  "id": 3,
  "name": "消しゴム",
  "price": 100,
  "createdAt": "2026-08-11T12:00:00Z"
}

このように、JSONは「受け取る」だけでなく「送る」場合にも使われます。

JSONを使ったWeb APIのよくある具体例

JSONはさまざまなWeb APIで使われています。ここでは、実際のサービスや一般的なパターンを見てみましょう。

1. 天気API

天気APIでは、緯度・経度や都市名を指定して、気温、湿度、降水量、天気コードなどを取得します。

Open-Meteoは、HTTP GETリクエストとクエリパラメータで利用でき、JSONを返すAPIとして説明されています。認証不要で使える範囲があるため、学習用の題材としても扱いやすいサービスです。

レスポンスイメージ：

Copy{
  "latitude": 35.7,
  "longitude": 139.7,
  "timezone": "Asia/Tokyo",
  "current_units": {
    "temperature_2m": "°C",
    "wind_speed_10m": "km/h"
  },
  "current": {
    "temperature_2m": 29.1,
    "wind_speed_10m": 12.3
  }
}

アプリはこの中から temperature_2m を取り出して「現在の気温：29.1℃」のように表示します。

2. GitHub API

GitHub REST APIでは、リポジトリ、Issue、Pull Request、ユーザー情報などを取得・操作できます。GitHubのドキュメントでは、メディアタイプとして application/vnd.github+json や application/json が使われることが説明されています。

Issue一覧を取得するAPIのイメージは次のようなものです。

Copy[
  {
    "id": 1001,
    "number": 1,
    "title": "READMEを更新する",
    "state": "open",
    "user": {
      "login": "octocat",
      "id": 1
    }
  },
  {
    "id": 1002,
    "number": 2,
    "title": "不具合を修正する",
    "state": "closed",
    "user": {
      "login": "hubot",
      "id": 2
    }
  }
]

配列の中にIssueオブジェクトが並び、それぞれにタイトル、状態、投稿者情報が入っています。

3. 決済API

StripeのAPIドキュメントでは、APIはRESTを中心に構成され、レスポンスはJSONエンコードされると説明されています。決済サービスでは、支払い情報、顧客情報、請求情報、エラー情報などがJSONで返ってきます。

決済エラーのレスポンスは、たとえば次のような形になります。

Copy{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "カードが拒否されました。"
  }
}

このようにエラー情報もJSONで返せば、アプリ側は code を見て処理を分けたり、message を画面に表示したりできます。

4. ECサイトの商品API

ECサイトでは、商品一覧、在庫、価格、レビューなどをAPIで取得することがあります。

Copy{
  "items": [
    {
      "id": "p001",
      "name": "コーヒー豆 200g",
      "price": 1280,
      "stock": 24,
      "categories": ["食品", "飲料", "コーヒー"]
    },
    {
      "id": "p002",
      "name": "マグカップ",
      "price": 980,
      "stock": 0,
      "categories": ["キッチン", "食器"]
    }
  ],
  "total": 2
}

stock が0なら「在庫なし」と表示し、categories を使ってカテゴリページへのリンクを作る、といった使い方ができます。

5. ログインやユーザー情報API

アプリにログインした後、ユーザー情報を取得するAPIでもJSONがよく使われます。

Copy{
  "id": 45,
  "name": "高橋美咲",
  "email": "misaki@example.com",
  "roles": ["user", "editor"],
  "lastLoginAt": "2026-08-10T21:15:00Z"
}

ここで roles が editor を含んでいれば、編集画面を表示する、といった制御ができます。

JSONのメリット

JSONが広く使われているのには理由があります。代表的なメリットを整理します。

1. 軽量である

JSONはタグをたくさん書く必要がないため、データ量を比較的少なくできます。通信量を抑えたいWeb APIでは、この軽さが役立ちます。

たとえば、同じ人物データをJSONで書くと次のようになります。

Copy{
  "firstName": "Taro",
  "lastName": "Yamada"
}

XMLで書くと、一般的には次のようになります。

Copy<person>
  <firstName>Taro</firstName>
  <lastName>Yamada</lastName>
</person>

XMLは開始タグと終了タグを使うため、構造が明確な一方で記述量は増えやすくなります。

2. 人間にも読みやすい

JSONはキーと値の組み合わせで書かれるため、慣れると内容を読み取りやすい形式です。

Copy{
  "name": "カフェラテ",
  "price": 480,
  "size": "M"
}

この程度のデータなら、プログラミング経験が浅くても意味を推測できます。

3. プログラムで扱いやすい

JSONは多くの言語で標準的にサポートされています。JavaScriptなら JSON.parse()、Pythonなら json モジュール、PHPなら json_decode() などを使って簡単に扱えます。

また、JSONのオブジェクトや配列は、プログラム上の辞書、連想配列、リスト、オブジェクトなどに変換しやすい形をしています。

4. Web APIとの相性がよい

現代のWeb APIでは、JSONがよく使われます。HTTPのレスポンスボディにJSONを入れ、Content-Type: application/json で形式を示すのが一般的です。

ブラウザのJavaScriptでも、Fetch APIの response.json() を使えば、レスポンスをJSONとして読み取れます。MDNのFetch API解説でも、response.json() によりレスポンスをJSONとして取得する流れが紹介されています。

5. 必要なデータ構造を表しやすい

JSONはオブジェクトと配列を組み合わせられるため、単純なデータから複雑なデータまで表現できます。

たとえば、記事、著者、タグ、コメントをまとめたデータも書けます。

Copy{
  "article": {
    "id": 10,
    "title": "JSON入門",
    "author": {
      "id": 3,
      "name": "編集部"
    },
    "comments": [
      {
        "id": 1,
        "body": "わかりやすかったです"
      },
      {
        "id": 2,
        "body": "APIの例が参考になりました"
      }
    ]
  }
}

このような入れ子構造は、Webアプリのデータ表現でよく登場します。

JSONの注意点・デメリット

便利なJSONですが、何でも万能というわけではありません。

コメントが書けない

JSONにはコメントを書くルールがありません。そのため、設定ファイルとして使う場合に説明を直接書けない点が不便に感じられることがあります。

Copy{
  "debug": true
}

このように書くことはできますが、次のようなコメントはJSONでは無効です。

Copy{
  // デバッグモード
  "debug": true
}

コメントを書きたい設定ファイルでは、JSON5やYAMLなど別の形式が選ばれることもあります。

日付型がない

JSONには日付専用の型がありません。多くの場合、日付は文字列として表現します。

Copy{
  "createdAt": "2026-08-11T10:00:00Z"
}

受け取った側は、この文字列を日付として解釈する必要があります。

同じキーの重複に注意が必要

RFC 8259では、オブジェクト内の名前は一意であることが望ましいとされています。重複したキーがある場合、受け取るソフトウェアによって挙動が異なる可能性があります。

Copy{
  "name": "田中",
  "name": "佐藤"
}

このようなJSONは避けます。実装によっては後ろの値だけが使われたり、エラーになったりすることがあります。

巨大なJSONは扱いにくい

JSONは軽量ですが、データ量が非常に大きくなると読み込みや解析に時間がかかります。大量のログ、画像データ、バイナリデータ、大規模な分析データには、別の形式が適していることもあります。

XMLとの違い

JSONとよく比較される形式にXMLがあります。XMLはExtensible Markup Languageの略で、タグを使ってデータ構造を表します。

まず、同じデータをJSONとXMLで比較してみましょう。

JSONの場合

Copy{
  "book": {
    "title": "JSON入門",
    "author": "山田太郎",
    "price": 1500
  }
}

XMLの場合

Copy<book>
  <title>JSON入門</title>
  <author>山田太郎</author>
  <price>1500</price>
</book>

どちらも同じようなデータを表せますが、書き方や得意分野が異なります。

比較項目	JSON	XML
書き方	キーと値、配列、オブジェクト	タグで囲む
記述量	比較的少ない	タグの分だけ多くなりやすい
読みやすさ	データ中心で読みやすい	文書構造には強いが冗長になりやすい
配列表現	`[]` で自然に表せる	同名タグの繰り返しなどで表す
Web API	現在よく使われる	既存システムや業務系で使われることも多い
コメント	使えない	使える
スキーマ	JSON Schemaなど	XML Schema、DTDなど
属性	ない	属性を持てる

AWSのJSONとXMLの比較でも、JSONは構文がよりコンパクトで、読み書きしやすい傾向があると説明されています。一方、XMLは文書構造や厳密なスキーマを扱う場面で使われ続けています。

つまり、JSONがXMLを完全に置き換えたわけではありません。Web APIやアプリ間通信ではJSONが選ばれることが多く、文書構造、既存の業務システム、規格化されたデータ交換ではXMLが使われる場面もあります。

JSONとXMLはどちらを選ぶべきか

新しくWeb APIを作る場合、多くのケースではJSONが扱いやすいでしょう。理由は、記述が短く、JavaScriptやモバイルアプリとの相性がよく、多くの開発者が慣れているからです。

一方で、次のような場合はXMLが候補になります。

既存システムがXMLを前提にしている
XML SchemaやDTDによる厳密な検証が必要
文書そのものの構造を細かく表したい
業界標準のデータ形式がXMLで定められている

選択の基準は「流行」ではなく、「データを受け渡す相手と目的」です。相手がJSONを期待しているならJSON、XMLを期待しているならXMLを使うのが基本です。

JSON:APIとは

少しややこしいのですが、「JSON」と「JSON:API」は別のものです。

JSONはデータ形式そのものです。一方、JSON:APIは、JSONを使ってAPIを作る際の構造やルールを定めた仕様です。JSON:API公式仕様では、クライアントがリソースを取得・変更する方法や、サーバーがどのように応答するかを定める仕様として説明されています。現在公開されているJSON:APIの仕様はバージョン1.1です。

JSON:APIのレスポンス例は次のような形です。

Copy{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:APIの基本"
    }
  }
}

通常のJSONは自由に構造を決められますが、JSON:APIでは data、type、id、attributes、relationships などの使い方にルールがあります。複数の開発者やサービス間でAPIの形式をそろえたい場合に役立ちます。

ただし、すべてのJSON APIがJSON:API仕様に従っているわけではありません。「JSONを返すAPI」と「JSON:API仕様のAPI」は区別して考えると混乱しにくくなります。

初心者がよく間違えるJSONの書き方

ここでは、実際によくあるミスをまとめます。

キーを引用符で囲んでいない

間違い：

Copy{
  name: "田中"
}

正しい：

Copy{
  "name": "田中"
}

シングルクォーテーションを使っている

間違い：

Copy{
  "name": '田中'
}

正しい：

Copy{
  "name": "田中"
}

最後にカンマがある

間違い：

Copy{
  "name": "田中",
  "age": 30,
}

正しい：

Copy{
  "name": "田中",
  "age": 30
}

コメントを書いている

間違い：

Copy{
  "debug": true // 開発中だけtrue
}

正しい：

Copy{
  "debug": true
}

真偽値の大文字小文字が違う

間違い：

Copy{
  "active": True
}

正しい：

Copy{
  "active": true
}

JSONは少しの記号ミスでも読み込みに失敗します。エラーが出たときは、カンマ、引用符、波括弧、角括弧の対応を確認すると原因を見つけやすくなります。

JSONを読みやすくするコツ

JSONは機械が読むものですが、人間が確認する機会も多いです。読みやすくするには、次の点を意識するとよいでしょう。

インデントをそろえる

読みにくい例：

Copy{"user":{"id":1,"name":"田中","roles":["admin","editor"]}}

読みやすい例：

Copy{
  "user": {
    "id": 1,
    "name": "田中",
    "roles": ["admin", "editor"]
  }
}

インデントを付けるだけで、構造がかなり見やすくなります。

キー名をわかりやすくする

Copy{
  "n": "田中",
  "a": 30
}

これでもJSONとしては有効ですが、意味が伝わりにくいです。

Copy{
  "name": "田中",
  "age": 30
}

このように書いたほうが、後から読んだ人にも伝わります。

単数・複数を意識する

配列には複数形のキー名を使うとわかりやすくなります。

Copy{
  "users": [
    {
      "id": 1,
      "name": "田中"
    },
    {
      "id": 2,
      "name": "佐藤"
    }
  ]
}

users という名前なら、複数のユーザーが入っていると直感的に理解できます。

JSONの安全面で知っておきたいこと

JSONはデータ形式ですが、扱い方を誤ると問題が起きることがあります。

特に古いJavaScriptの書き方では、JSON文字列を eval() で実行して読み込む例がありました。しかし、RFC 8259でも、JSONテキストを eval() のような関数で解析することはセキュリティ上のリスクがあると説明されています。JSONを読み込むときは、言語や環境が用意しているJSONパーサーを使います。

JavaScriptなら JSON.parse() を使います。