JSONとは？非開発者の店主のための入門ガイド

こんにちは、3Min APIの開発をリードしているyeonghyeonです。

前回のAPI編で、「APIは決められたアドレスに決められた形のメッセージを送受信する窓口です」とお伝えしました。そのとき「メッセージの形」の話はあえて後回しにしていましたが、今日はその最後のピースです。器（データベース）と通路（API）のあいだを実際に行き来する「メッセージ」の形、つまりJSONの話です。

今日の記事のゴールは「文法を暗記する」ことではありません。「自分のビジネスの一つの出来事を、JSONの一塊で書ける」という感覚、そこに届けば十分です。この感覚さえあれば、これから開発者やAIと会話するとき、お互いの言葉の距離が一段近づきます。事前知識は要りません。

JSONとは何か

まず辞書的な定義から短く見ておきます。WikipediaはJSON（JavaScript Object Notation）を「属性と値の組、および配列データで構成された、人間が読めるテキストを用いてデータを表現するためのオープンな標準フォーマット」と説明しています。

一行でまとめるとこうです。

JSON = システム同士でやり取りするデータを、人間の目でも読めるように、決められた書き方で書き留めたテキスト。

システム同士でメッセージをやり取りする方法には、実はJSON以外にもXML、YAML、Protocol Buffersなどいくつかの選択肢があります。それでも今日のWeb APIが圧倒的にJSONを選ぶ理由はシンプルです。人間にとっても、プログラムにとっても、一目で理解しやすいからです。プログラマーがメモ帳で開いても読めますし、サーバーが解析しても速い。この二つを同時にこなせるフォーマットはそれほど多くありません。

なぜ「決まった形」が必要なのか

前の二編で、器（DB）と通路（API）という道具が手に入りました。しかし道具があるだけでデータが勝手に流れ出すわけではありません。窓口にやってくる人が毎回違う紙にバラバラの書き方をしてきたら、係員は一件も処理できません。

だから銀行は、入金伝票・出金伝票・送金依頼書のように書式をあらかじめ決めておきます。同じ書式だからこそ窓口係が素早く検証でき、記録も自動で残せます。APIも同じ理由で、「この窓口に来るメッセージはこういう形にしてください」という約束をあらかじめ固めます。その「形」を書き起こす標準文法がJSONです。

JSONが定着する前は、システムごとにメッセージの形式がバラバラでした。あるところはカンマ区切りの一行テキスト、あるところはタグで包んだXML、あるところは独自のバイナリフォーマットを社内文書だけで共有する、という具合です。新しい取引先が増えるたびに仕様書を読み解き、パースするコードを書き直していました。JSONが事実上の標準になった今は、「JSONでやり取りしましょう」の一言でたいていの連携が始まります。

ExcelでJSONを理解する

JSONの文法をいきなり見る前に、既に慣れ親しんだExcelから始めてみましょう。Excelシートを一枚思い浮かべてみてください。一番上の行は列名（商品名、数量、金額…）で、その下の各行が1行＝1件の取引を表します。

この構造をそのままJSONに移すと、ごく自然に対応がつきます。

• Excelの列名 → JSONのキー（key）
• セル一つに入った値 → JSONの値（value）
• Excelの1行 → JSONのオブジェクト1つ（{}）
• Excelの複数行 → JSONの配列（[]）

注文シートの1行が、以下のような表だとしてみましょう。

order_id	product	quantity	amount
A-2026-0001	Château Margaux 2020	2	480000

この1行をそのままJSONオブジェクトに移すと、次のようになります。

{
  "order_id": "A-2026-0001",
  "product": "Château Margaux 2020",
  "quantity": 2,
  "amount": 480000
}

名前の横にコロン一つ、項目のあいだにカンマ一つ、全体を包む中括弧一組。ルールはこれだけです。この一塊こそ、Excelの1行と同じ情報を収めたJSONオブジェクトです。

ではExcelがあるのに、なぜJSONが別に必要なのでしょうか。違いは階層と柔軟さの二つです。Excelは1セルの中にさらに表を入れるのが難しく、行ごとに列構成が変わると管理がすぐに崩れます。対してJSONは、値の場所にさらにオブジェクトや配列を自然に入れられますし、注文ごとに異なる可能性のあるオプション項目も無理なく収まります。Excelが「平たい帳簿」なら、JSONは「必要なときにフォルダのように折りたためる帳簿」に近いです。

ワインショップ店主の注文伝票

前回の場面を続けましょう。オンラインショップから新しい注文が1件届きます。店舗POSも提携レストランも同じデータベースを見ており、そのあいだを繋ぐ通路がAPIでした。さて、このAPIの窓口に実際に飛び込んでくるメッセージを覗いてみましょう。

オンラインショップがワインショップの「注文作成API」に、こんな形のJSONを一塊で送ってきます。

{
  "order_id": "A-2026-0412",
  "customer": {
    "id": "C-00871",
    "name": "Alex",
    "email": "alex@example.com"
  },
  "items": [
    {
      "sku": "WINE-MARGAUX-2020",
      "name": "Château Margaux 2020",
      "quantity": 2,
      "unit_price": 240000
    },
    {
      "sku": "WINE-OPUS-2019",
      "name": "Opus One 2019",
      "quantity": 1,
      "unit_price": 520000
    }
  ],
  "total_amount": 1000000,
  "ordered_at": "2026-04-15T14:23:00+09:00"
}

この一塊の中に、誰が（customer）、何を（items）、いくらで（total_amount）、いつ（ordered_at）買ったかがすべて収まっています。先ほど言った「平たい帳簿ではなく折りたためる帳簿」の意味が、ここで一目で見えるはずです。顧客は詳細（名前、メール）を持つ一つの塊であり、購入品目は2件のリストです。Excelなら顧客シート、注文シート、注文明細シートに分けて管理しなければならなかった情報が、一つの封筒の中にきれいに収まっています。

API窓口はこの封筒を受け取った瞬間に、「約束された形」に合っているか検査します。order_idが空だったり、quantityに数字以外の値が入っていたり、customerの中にemailが無ければ、その場で拒否します。おかげでデータベースには常に同じ形で注文が積み重なり、あとで統計を出したり別のシステムへ書き出したりするときも迷うことがありません。

決済が終わると、決済会社はワインショップの別の窓口に向けて「この注文の決済が成功しました」というJSONを送り返してきます。こうして相手のシステムの方から先に知らせてくる方式を、区別してWebhookと呼ぶと前回お伝えしました。Webhookの本文も当然JSONです。リクエストもJSON、レスポンスもJSON、通知もJSON。システム同士を行き交うほぼすべてのメッセージが同じ形式である――この一点が、今のインターネットをここまで滑らかに動かしています。

JSONの文法：キー・値・オブジェクト・配列

ここで文法をごく簡単に整理します。JSONが持つルールは驚くほど少ないです。以下の4つさえ押さえれば、99％のJSONは読めるようになります。

1) キーと値のペア ― 最小単位

基本は「名前」と「中身」をコロン一つで結んだ組です。名前は必ずダブルクォートで囲みます。

"product": "Château Margaux 2020"

2) 値の種類 ― 4つの基本型 + 2つの構造

値の場所に来られるものは決まっています。

• 文字列：ダブルクォートで囲んだ文字。例）"Alex"
• 数値：クォート無しでそのまま。例）480000
• 真偽：true または false（クォート無し）
• 空：null（まだ値が無いという意味）
• オブジェクト：中括弧{}で囲ったキーと値の集まり
• 配列：角括弧[]で囲った値の並び

3) オブジェクト {} ― キーと値の束

いくつかのキーと値のペアをカンマで繋ぎ、中括弧で包むと、一つのオブジェクトになります。Excelの1行がこのオブジェクト1つに対応します。

{
  "name": "Alex",
  "email": "alex@example.com",
  "is_member": true
}

4) 配列 [] ― 同じ形の並び

角括弧の中に値をカンマで並べれば配列です。Excelの複数行がこの配列1つに対応します。

[
  { "sku": "WINE-MARGAUX-2020", "quantity": 2 },
  { "sku": "WINE-OPUS-2019",    "quantity": 1 }
]

そしてここが本当に大事なポイントです。いま見た配列の中の要素がまたオブジェクトだったことに気づかれたと思います。値の場所には、オブジェクトも配列もまた入れられます。この再帰的ルールたった一つのおかげで、JSONはどれほど複雑な情報も入れ込めます。ワインショップの注文伝票のように「1件の注文の中に複数の商品があり、各商品の中に名前と数量と単価がある…」を表現できるのは、まさにこの仕組みのおかげです。

整理するとJSONは「キーと値が基本で、それをオブジェクトにまとめ、オブジェクトを配列で並べられる。そして値の場所にまたオブジェクトや配列が入ってくる。」この一文ですべてです。

JSONはどこで使われているか

ワインショップの注文伝票の外でも、JSONはすでに私たちの日常の奥深くに入り込んでいます。目立たないだけです。

• モバイルアプリとサーバーの通信：Instagramのフィード、デリバリーアプリの店舗一覧、株価アプリの相場 ― ほとんどすべてJSONで行き交います。
• 設定ファイル：VS Codeの設定や、多くの開発ツールの環境ファイルがJSON形式です。人間が自分で開いて直せるようにと、あえてJSONを選んでいます。
• 公開データ・オープンデータ：政府や公共機関が開放するデータAPIの相当数がJSONで応答します。
• SaaS連携・Webhook：決済会社、配送会社、メッセージングプラットフォーム、メール配信サービスが送ってくる通知はすべてJSONの塊です。
• AI・LLMの構造化出力：ChatGPTやClaudeといったモデルに「結果をJSONで返してください」と頼むと、すぐ使える形で返してくれます。JSONはAIとビジネスシステムをつなぐ共通語でもあります。

JSONを「形式が自由なデータ」と勘違いすると困ります。むしろ逆です。Chae-wonさんが先に書いたデータにも計画が必要ですで強調されていたとおり、JSONが力を発揮するのは「このエンドポイントのJSONはこういうフィールドを持つ」という約束が事前に明確になっているときです。自由なのは文法であって、フィールド設計ではありません。この区別さえ覚えておけば、JSONを取り巻く誤解のほとんどは消えます。

ここまでの整理 ・ シリーズの締めくくり

3部作を一度にまとめてみます。

• 1編 データベース ― ビジネスのデータを同じ形で積み上げる器を作りました。
• 2編 API ― その器に外の世界が安全に近づくための通路（窓口）を据えました。
• 3編 JSON ― その窓口を行き交うメッセージの形を決めました。

この三つが揃った瞬間、あなたのビジネスは初めて人の手を離れても動き続けるシステムの姿を手に入れます。オンラインショップから注文が入れば、JSON一塊がAPI窓口を通ってDBに積まれ、決済会社がJSON一塊で決済結果を知らせ、店舗POSがJSON一塊で在庫を減らす。店主が眠っているあいだも、同じ約束の上をメッセージたちが行き交います。自動化という言葉の実体は、結局この三つの約束の組み合わせなのです。

さらに大切なのは、この三つの概念さえ掴めば、今後出会うあらゆる新しい用語（GraphQL、イベントストリーミング、MCP、AIエージェント…）が、この骨格の上に積まれる変奏にすぎないという点です。骨が通っていれば、枝葉はすぐに追いついてきます。

今日すぐ試せること

シリーズの最終回ですから、実習も前の二編と繋がるように設計しました。紙とAI、そしてブラウザが一つあれば十分です。

Action 1. 自分のビジネスの一つの出来事をJSONで書いてみる

前回のAPI編で選んだ出来事（例：注文作成、予約登録、問い合わせ受付）を一つ取り出してください。そこに含まれる項目をそのままJSON一塊に移してみればOKです。最初は平たく書いても構いませんし、慣れてきたら顧客や商品のように塊が大きくなる箇所をオブジェクトの中のオブジェクトとして折りたたんでみてください。

{
  "reservation_id": "R-2026-0001",
  "customer": {
    "name": "Alex",
    "phone": "+81-90-xxxx-xxxx"
  },
  "date": "2026-05-12",
  "party_size": 4,
  "note": "窓際の席を希望"
}

この一塊こそが、「自分の仕事の一つの出来事」をシステムが読める形に移した結果です。開発者がAPIの仕様を起こすときも、まさにこの段階から始めます。

Action 2. AIと検証サイトで文法をチェックする

Action 1で書いたJSONを、ChatGPT、Claude、Geminiなどに貼り付けて、こう頼んでみてください。

下のJSONが文法的に正しいかチェックしてください。
タイポ、クォート、カンマ、中括弧・角括弧の対応が合っているかを指摘し、
非開発者でも分かる言葉で直すべき箇所を教えてください。

[ここに Action 1 のJSONを貼り付け]

目で追加検証したければ、JSONLintのような公開検証サイトに貼り付けてください。緑の「Valid JSON」が出れば文法はパスです。この二段階を繰り返すだけでも、JSONを見る目は一気に鋭くなります。

Action 3. 自分のエンドポイントで形式を壊してみる

前回のAPI編のクイックスタートに沿って3Min APIで最初のエンドポイントを作られた方もいらっしゃると思います。今日はそのエンドポイントの詳細ページに戻り、同じエンドポイントに対して二つの実験を行ってみてください。

1. フィールド構造を変えてみる ― 必須項目を一つ追加したり、名前を変えたりした上で、新しいJSONの形で呼び出し、正常に保存されるか確認してみてください。
2. わざと壊れたJSONを送ってみる ― カンマを抜いたり、必須フィールドを空にしたり、数値の場所に文字を入れたりして呼び出してみてください。API窓口がどんなエラーで返してくるかを自分の目で確認することが核心です。

返ってくるエラーメッセージの意味と対処法はトラブルシューティングガイドにまとめてあります。「エラーが出たら慌てる」ではなく「エラーコードを見て原因を絞り込む」に切り替わった瞬間、あなたはすでにシステムと会話する言葉を身につけています。

👉 まだエンドポイントがない方は ― 3分クイックスタート

3部作を終えて ― これからどこへ向かいますか

ここまで読んでいただいた今、あなたは三つの道具を手にしています。ビジネスのデータを積み重ねる器、外と安全に出入りする通路、そして通路の上を行き交うメッセージの形。もちろんこの三つの主題の中には、さらに深い細部があります。しかし今日までの理解だけでも、あなたのビジネスをITエコシステムの上で広げ、さらにAI時代に備えるための骨格は十分に整っています。残りの細部は、必要になった瞬間にその上に乗せていけば大丈夫です。

ここで「これって開発者の仕事じゃないの？」という疑問が浮かぶかもしれません。しかし最近はAIのおかげで、開発者と非開発者の境界が以前よりずっと薄くなりました。私がお勧めしているのは、直接コードを書いてくださいという意味ではなく、ITが動く核心の原理を感覚として身につけておいてくださいということです。この感覚の上で、良い道具の力を借りて、小さなAPIを作って、呼び出して、エラーにぶつかりながら直していく循環が始まります。この循環が積み重なれば、ふとした瞬間に「自分のビジネスのこの部分も自動化できるかも」という考えが自然と浮かんできます。この感覚こそが、ビジネスをより広い市場へと押し出す出発点です。

骨格が通ったあとに、面白いことが一つ起こります。最近よく耳にするはずの自動化ツール、たとえばn8n、Zapier、Makeのようなサービスを開いてみれば、これらが全部API + JSON + DBという同じ骨格の上で動いているのが一目で見えるはずです。「Googleスプレッドシートに1行追加」はGoogleが提供するSheets APIを、「Gmailでメール送信」はGmail APIを、「Driveにファイルアップロード」はDrive APIを呼び出しているだけです。これらのツールは結局、すでに公開されている数多くのAPIをJSONで繋ぐ仲介役に過ぎません。骨格を理解している人は、同じツールをずっと主体的に使いこなせます。

ではいま何をすべきでしょうか。私のおすすめはこうです。全体の流れを大まかにでも掴んだなら、まずは小さく当てはめて、実験し、ぶつかってみてください。運用が大きくなり、必要性がはっきりしてきたタイミングで自前のシステムを考えても遅くありません。今ほど小さく始めるのに良い時代はありません。クラウド、公開API、LLM、ノーコードツールが、そのはじめの一歩を支えてくれます。

AIとビジネスの噛み合わせについて、より広い視点が欲しい方には小規模ビジネスのAI準備 — データ、API、そして今やるべきことが次の読み物としておすすめです。

器、通路、メッセージ。この三つの約束の上で、あなたのビジネスは人の手を離れても動き出します。3部作を最後まで読んでくださり、ありがとうございました。

---

← 前の記事：APIとは？非開発者の店主のための入門ガイド