JSONスキーマ検証（JSON Schema Validation）開発ガイド

ドキュメント

• documentation/docs/content_03_concepts/06-security-extensions/concept-03-schema-validation.md

  - JSONスキーマ検証概念

機能概要

JSONスキーマ検証は、入力データの構造・型・制約を検証する層。

• JSON Schema Draft 2020-12準拠
• ユーザー登録検証: テナント別カスタムスキーマ
• Identity Verification検証: 本人確認申請データ検証
• 外部API検証: リクエスト/レスポンス検証
• 詳細エラーメッセージ: フィールド別エラー

モジュール構成

libs/
└── idp-server-platform/                     # プラットフォーム基盤
    └── .../platform/json/schema/
        ├── JsonSchemaDefinition.java       # スキーマ定義
        ├── JsonSchemaValidator.java        # スキーマ検証
        └── JsonSchemaValidationException.java

ユーザー登録でのスキーマ検証

idp-server-core/openid/identity/IdPUserCreator.java

内:

public class IdPUserCreator {

    JsonSchemaDefinition definition;
    AuthenticationInteractionRequest request;

    public User create() {
        User user = User.initialized();

        // スキーマ定義に基づいてフィールドを設定
        if (definition.hasProperty("name") &&
            request.containsKey("name")) {
            user.setName(request.getValueAsString("name"));
        }

        if (definition.hasProperty("email") &&
            request.containsKey("email")) {
            user.setEmail(request.getValueAsString("email"));
        }

        // その他のフィールドも同様に処理
        // ...

        return user;
    }
}

注意: JsonSchemaDefinitionが、許可されたフィールドを定義します。

スキーマ定義例

ユーザー登録スキーマ

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "birthdate": {
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
    }
  },
  "required": ["email", "name"]
}

Identity Verification申請スキーマ

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "enum": ["passport", "drivers_license", "national_id"]
    },
    "document_number": {
      "type": "string",
      "minLength": 5
    }
  },
  "required": ["document_type", "document_number"]
}

スキーマ検証エラー

public class JsonSchemaValidationException {
    // フィールド別の詳細エラーメッセージ
    // - 必須フィールド不足
    // - 型不一致
    // - フォーマット違反
    // - 制約違反（minLength, maxLength, pattern等）
}

E2Eテスト

e2e/src/tests/
└── integration/ida/
    └── (Identity Verificationスキーマ検証テスト)

コマンド

# ビルド
./gradlew :libs:idp-server-platform:compileJava

# テスト
cd e2e && npm test -- integration/ida/

トラブルシューティング

スキーマ検証失敗

• スキーマ定義が正しいか確認（JSON Schema Draft 2020-12形式）
• 必須フィールドが含まれているか確認

型エラー

• フィールドの型がスキーマと一致するか確認
• string, number, boolean, object, arrayを正しく使用

フォーマット検証失敗

• email, uri, date-time等のフォーマットが正しいか確認
• カスタムpattern（正規表現）が正しいか確認

カスタムスキーマが反映されない

• テナント別スキーマ設定が正しいか確認
• JsonSchemaDefinitionが正しくロードされているか確認