手で書き換えたAPIレスポンスのサンプルJSONに、末尾のカンマを1つ消し忘れただけで検証環境がまるごと落ちたことがあります。原因が「JSON構文エラー」だと分かるまでにログを何往復も行き来しました。それ以来、JSONは「手で触るもの」ではなく「ツールを通して触るもの」だと考えるようにしています。このシリーズは、その考えに至るまでの整理記録です。

JSONとは

JSONがWeb API・設定ファイル・NoSQL・ログの4つの場面で使われていることを示す図

図1: JSONは特定の言語・用途に縛られず、データ交換の共通言語として広く使われている

JSON（JavaScript Object Notation）は、JavaScriptのオブジェクトリテラルをベースにした軽量なデータ記述形式です。名前の通りJavaScript由来ですが、現在では言語を問わず使われる汎用フォーマットとなっており、RFC 8259 として標準化されています。

中括弧 { } でオブジェクト（キーと値の集合）、角括弧 [ ] で配列（値の並び）を表現するシンプルな構文だけで、ネストした複雑な構造まで表現できる点が最大の特徴です。人間にも読めて、かつプログラムからの扱いやすさを重視して設計されています。

主な用途 — どこで使われているか

JSONは「アプリケーション同士がデータをやり取りする」場面のほぼすべてに登場すると言っても過言ではありません。

Web API
REST APIのリクエストボディ・レスポンスの事実上の標準形式。GraphQLのレスポンスもJSON。
設定ファイル
package.json・tsconfig.jsonなど、ツールチェーンの設定はJSONが多い。
NoSQL / ドキュメントDB
MongoDBはBSON（JSONのバイナリ表現）、DynamoDBもJSON構造でドキュメントを保存する。
ログ・メッセージング
構造化ログの出力形式や、Kafka・SQSなどのメッセージキューのペイロード形式として採用される。

このように「アプリの中のコード」ではなく「アプリとアプリの境界」でJSONが選ばれる場面が非常に多く、実務でJSONを一切扱わずに済むエンジニアはほとんどいないと言えるでしょう。

YAML・XMLとの比較（○×表）

同じ「構造化データの記述形式」として比較されることが多いYAML・XMLと、実務でよく問題になる観点で比較しました。○＝標準で対応、△＝実装や運用でカバー可能、×＝標準では非対応という基準です。

観点 JSON YAML XML
プログラムからの扱いやすさ ○ 仕様がシンプルで一貫 △ パーサー依存の差異あり △ スキーマ定義は強力だが複雑
パース速度 ○ 高速 × YAMLより低速な傾向 △ ツール・実装依存
コメントの記述 × 標準では非対応 ○ # で可能 △ <!-- -->で可能
人間にとっての読みやすさ △ 括弧・クォートが多い ○ 記号が少なく高い × 閉じタグで冗長
言語標準ライブラリでの対応 ○ ほぼ全言語で標準搭載 △ 追加ライブラリが必要な言語も △ 標準搭載だがAPIが煩雑

💡 使い分けの目安

「プログラム同士が高速にやり取りするデータ」にはJSON、「人間が読み書きする設定ファイル」にはYAML、というのが実務での大まかな使い分けです。両者は競合するというより、用途によって自然に棲み分けています。

なぜツールを使うべきか — 手打ち編集のリスク

JSONの構文はシンプルですが、シンプルであるがゆえに「融通が利かない」という側面もあります。以下は、手でJSONを編集していると起こりがちな典型的な事故です。

  • 末尾カンマ — 配列やオブジェクトの最後の要素にカンマを付けるとエラーになる（JavaScriptのオブジェクトリテラルでは許容されるため混同しやすい）
  • クォートの種類 — キーや文字列値はダブルクォート必須。シングルクォートやクォート無しは不可
  • コメントの混入 — 標準のJSONにコメントは書けないため、他形式からの書き換え時に消し忘れて構文エラーになる
  • 数値と文字列の取り違え — "port": "8080" と "port": 8080 は型が異なり、呼び出し側での扱いが変わる

これらは目視でのレビューでは見落としやすく、しかもエラーメッセージが「どこが悪いか」を的確に教えてくれないパーサーも少なくありません。だからこそ、整形・検証ツールやエディタ拡張機能を使い、構文エラーをその場で機械的に検出できる環境を整えておくことが重要になります。

⚠️ 「動いていたから大丈夫」は通用しない

JSONを手で書き換える機会は、開発中よりもむしろ本番トラブル対応やデータ移行時の方が多いものです。焦っている状況でこそ構文ミスが起きやすく、かつ気づきにくいという事情があります。平常時からツールを使う習慣をつけておくことが、いざという時の事故を防ぎます。

本シリーズの構成

全5回で、ツール導入から基本文法、構造設計・スキーマ検証、CI組み込みまでを実務者向けに一通り解説します。

PART内容
01（本記事）JSONの特徴、用途、YAML/XMLとの比較
02ツール導入 — 整形・検証ツールとエディタ拡張機能
03基本文法とデータ型 — 実務で誤りやすいポイント
04構造設計とJSON Schemaによる検証自動化
05実践例とCI組み込み、まとめ

✅ 次の章では…

PART 02 では、オンライン整形・検証ツールの選び方と、VS Codeを中心としたエディタ拡張機能の導入手順を具体的に解説します。

→ PART 02 — ツール導入へ