JSON チュートリアル

JSON Schema とは？使い方、例、完全チュートリアル（2026）

読了約 12 分

API レスポンスや設定ファイルを扱う際、JSON 構文が正しいからといってデータが「有効」とは限りません——フィールド欠落、型エラー、値の範囲外は、しばしばランタイムまで表面化しません。JSON Schema はまさにこの問題を解決するために生まれた規格です。本文では定義と使用シーンから出発し、基本書き方、よく使うキーワード、実践検証フロー、ツール選定まで段階的に解説し、実用的な JSON データ制約方式を構築する手助けをします。

読む前の概要

項目 説明
コア課題 JSON 構文は正しいが、構造や値が業務約定に合致しない
解決アプローチ Schema でフィールド型、必須項目、制約を宣言し、自動検証
推奨バージョン Draft 2020-12（エコシステムサポートが最も成熟）
本文カバー範囲 定義 → 書き方 → キーワード → 実践 → 選定 → FAQ

JSON Schema とは？

JSON Schema は JSON ベースの規格で、「JSON データが満たすべき条件」を記述します。データの型宣言 + 制約ルールと理解できます：どのフィールドが必須か、各フィールドの型、文字列長や数値範囲、配列要素が満たすべき構造——すべて Schema に記述できます。

それ自体も有効な JSON ドキュメントですが、セマンティクスが異なります——Schema は業務データを載せず、業務データの形状を記述します。OpenAPI 3.x は JSON Schema でリクエスト/レスポンスボディを記述；多くの CLI ツールは Schema で設定ファイルを検証；フロントエンドフォームライブラリも Schema 駆動検証ロジックをよく使います。習得後、フロントエンド、バックエンド、CI パイプラインで同一制約定義を再利用し、「各クライアントが独自検証を書く」重複労働を削減できます。

なぜ JSON Schema が必要？

日常開発では、JSON.parse() は括弧の対応、引用符の正しさしか教えてくれません。以下の状況では構文検証は完全に無力です：

  • インターフェースが email フィールドを要求するが、レスポンスに欠落
  • age は整数のはずが、クライアントが文字列 "25" を送信
  • 列挙フィールド status に約定外の値 "unknown" が出現
  • ネストオブジェクト address.zip が郵便番号形式に合致しない

JSON Schema の価値は：上記の「暗黙の約束」を実行可能、共有可能、バージョン管理可能な宣言に変えること。チームは Code Review 段階で Schema と照合してインターフェース変更を確認でき、連携調整や本番後までフィールド不一致に気づかない状況を避けられます。

JSON Schema 基本的な使い方と例

最もシンプルな Schema は $schema（使用する規格バージョン）とルートレベル type を宣言する必要があります。以下はユーザーオブジェクトを記述：name 必須文字列、age 任意非負整数。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "ユーザー氏名"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

対応する有効なデータインスタンス：

{ "name": "田中", "age": 28, "email": "tanaka@example.com" }

{ "age": 28 }（必須 name 欠落）、または { "name": "山田", "extra": true }（additionalProperties: false で追加フィールド禁止）を渡すと、検証器は明確なエラーパスと原因を返します。

よく使うキーワード早見表

Draft 2020-12 で開発者が最も頻繁に使うキーワードは以下。Schema 記述時にほぼ必ず使います：

キーワード 役割 サンプル
type データ型を宣言 "string" / "integer" / "object"
properties オブジェクトのフィールド定義 { "id": { "type": "integer" } }
required 必須フィールド一覧 ["id", "name"]
enum 列挙値を限定 ["draft", "published"]
format 一般的な文字列形式 "email" / "date-time"
$ref 他 Schema フラグメントを参照 "#/$defs/Address"

複雑な Schema は $defs で再利用可能フラグメント（Address、Pagination など）に分割し、$ref で参照することを推奨。単一ファイルの肥大化を避けられます。

JSON Schema と JSON 構文検証の違い

両者は異なるレイヤーの問題を解決し、実践では通常組み合わせて使用します：

  • 構文検証：括弧、引用符、カンマが有効か → JSON.parse 可能か
  • Schema 検証：フィールド、型、制約が約定に合致するか → 業務ルールを通過するか

推奨ワークフロー：まず生テキストを JSONSort に貼り付けてフォーマットと構文チェック。問題なければ ajv、fastjsonschema などのライブラリで Schema 検証。ローカルツールが構文層、Schema が意味層——役割分担が明確です。

実践：API 契約検証フロー

典型的な REST プロジェクトを例に、完全フローを 4 ステップに分解できます：

  1. Schema 定義：リポジトリで schemas/user.json を保守し、OpenAPI または API ドキュメントとバージョン同期。
  2. サンプル記述：有効と不正の各 1 件を提供し、単体テスト fixture として使用。
  3. CI 統合：PR パイプラインで Mock レスポンスと Schema の一致を検証し、フィールドの意図しない削除・改名を防止。
  4. ランタイムフォールバック：サーバー側でリクエストボディ受信時に Schema 検証を実行し、400 と構造化エラーを返し、不正データの DB 書き込みを防ぐ。

このフローの核心メリットは変更の可視化：インターフェースフィールド変更が CI 段階で捕捉され、人的記憶や連携時の偶然発見に依存しません。

JSON Schema と他方式の比較

方式 長所 限界
JSON Schema 言語非依存、OpenAPI ネイティブサポート、成熟エコシステム 複雑ルールの表現力に限界、学習曲線あり
TypeScript 型 IDE 体験良好、コンパイル時チェック TS エコシステム限定、ランタイムは追加変換が必要
手書き if/else 検証 柔軟、追加依存なし 保守困難、再利用困難、境界ケース漏れやすい
Protobuf / Avro 強型、高性能シリアライズ コンパイルステップ必要、純 JSON API シーンに不向き

API が既に JSON + OpenAPI なら、JSON Schema は通常最低摩擦の選択；フルスタック TypeScript で言語横断契約不要なら、TS 主体、Schema 補助が可能です。

JSON Schema に投資する価値は？

投資を推奨するシーン：

  • 外部 API 提供。呼び出し元と機械可読契約を共有する必要がある
  • 設定ファイル構造が複雑。デプロイ前に形式エラーを阻止したい
  • 複数クライアント（Web / モバイル / バックエンド）で同一データ制約を共有
  • CI でインターフェース breaking change を自動検出する必要がある

延期可能なシーン：

  • たまに JSON をフォーマット・閲覧するだけ → JSONSort で十分
  • データ構造が極めてシンプルで長期不変 → 手書き検証の方がコスト低
  • チームに OpenAPI / 契約テストフローなし → まずドキュメント習慣を確立してから Schema 導入

よくある質問（FAQ）

JSON Schema とは？

JSON Schema は JSON データ構造と制約を記述するルール集です。それ自体が JSON ドキュメントで、フィールド型、必須項目、値範囲などを宣言し、検証器がデータ合法性を自動判定します。

JSON Schema と JSON の違いは？

JSON は業務データを載せる；JSON Schema はそのデータがどうあるべきかを記述。比喩：JSON は「インスタンス」、Schema は「金型」。

どのバージョンを選ぶべき？

新規プロジェクトは Draft 2020-12 を優先。旧プロジェクトが Draft-07 / 2019-09 使用中なら、新バージョンキーワード依存でなければ強制移行不要。

ローカルでどう検証する？

構文層は JSONSort でフォーマットとチェック；Schema 層は ajv（Node.js）、jsonschema（Python）、VS Code JSON Schema プラグイン。

OpenAPI と JSON Schema の関係は？

OpenAPI 3.x のリクエスト/レスポンスボディ定義は JSON Schema のサブセットをベースに拡張。OpenAPI ドキュメントを書くことは本質的に Schema を書くこと。

結論

JSON Schema が解決するのは「JSON が解析できるか」ではなく「データがチーム約定に合致するか」。定義、書き方から CI 統合まで、その価値は暗黙ルールを明示的・実行可能な契約に変えること。小さなインターフェースや設定ファイルから最初の Schema を書き検証を組み込み、段階的に全プロジェクトへ拡張することを推奨します。

関連記事

更新ログ： 初稿公開