JSON Schemaバリデーション

JSON Schemaは、JSONドキュメントにアノテーションを付けてバリデーションするための語彙です。JSONデータの期待される構造、データ型、制約、ドキュメントを機械可読な形式で記述できます。JSONの型システムと考えてください。有効なデータがどのようなものかを定義することで、不正な入力を自動的に拒否できます。

基本的なスキーマ構造:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

このスキーマは、有効なデータは必須の name 文字列（1文字以上）、オプションの非負整数 age、必須の email 文字列を持つobjectでなければならないと宣言します。

主要なバリデーションキーワード:

• type: JSON型を制限（string、number、integer、boolean、null、object、array）
• properties: objectプロパティのスキーマを定義
• required: 必須プロパティ名をリスト
• items: array要素のスキーマ
• enum: 値を固定セットに制限
• pattern: 文字列の正規表現パターン
• minimum/maximum: 数値範囲の制約
• minLength/maxLength: 文字列長の制約
• oneOf/anyOf/allOf: ブール論理でスキーマを合成

JSON Schemaが重要な理由:

スキーマバリデーションがなければ、アプリケーションは受信JSONデータのすべてのフィールド、型、制約を手動でチェックする必要があります。これはバリデーションロジックの分散、一貫性のないエラーメッセージ、見逃されるエッジケースにつながります。JSON Schemaはバリデーションを単一の宣言的な定義に集約し、フロントエンドとバックエンドで共有し、ドキュメント生成に使用し、独立してテストできます。

開発者がよくやるミス:

よくあるミスは、許容範囲が広すぎるスキーマを書くことです。properties を定義せずに "type": "object" を使用すると、入力がobjectであることは検証しますが内容はチェックしません。もうひとつのミスは、予期しないフィールドを拒否したい場合に "additionalProperties": false を忘れることです。また、required（objectスキーマ上の配列）と個々のプロパティを必須にすることを混同する開発者もいます。プロパティ定義内に "required": true を置くのは無効です。

ベストプラクティス:

API境界でJSON Schemaの使用を開始し、すべての受信リクエストを検証しましょう。新しいプロジェクトには最新のドラフト（2020-12）を使用してください。スキーマからドキュメントとTypeScript型を生成して同期を保ちましょう。Ajv（JavaScript）、jsonschema（Python）、everit-org/json-schema（Java）などの十分にメンテナンスされたバリデーターライブラリを使用してください。有効・無効の両方の例が期待通りに動作することを検証するスキーマテストを作成しましょう。