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 内:

java
1public class IdPUserCreator {
2
3    JsonSchemaDefinition definition;
4    AuthenticationInteractionRequest request;
5
6    public User create() {
7        User user = User.initialized();
8
9        // スキーマ定義に基づいてフィールドを設定
10        if (definition.hasProperty("name") &&
11            request.containsKey("name")) {
12            user.setName(request.getValueAsString("name"));
13        }
14
15        if (definition.hasProperty("email") &&
16            request.containsKey("email")) {
17            user.setEmail(request.getValueAsString("email"));
18        }
19
20        // その他のフィールドも同様に処理
21        // ...
22
23        return user;
24    }
25}

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

スキーマ定義例

ユーザー登録スキーマ

json
1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "type": "object",
4  "properties": {
5    "email": {
6      "type": "string",
7      "format": "email"
8    },
9    "name": {
10      "type": "string",
11      "minLength": 1,
12      "maxLength": 100
13    },
14    "birthdate": {
15      "type": "string",
16      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
17    }
18  },
19  "required": ["email", "name"]
20}

Identity Verification申請スキーマ

json
1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "type": "object",
4  "properties": {
5    "document_type": {
6      "type": "string",
7      "enum": ["passport", "drivers_license", "national_id"]
8    },
9    "document_number": {
10      "type": "string",
11      "minLength": 5
12    }
13  },
14  "required": ["document_type", "document_number"]
15}

スキーマ検証エラー

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

E2Eテスト

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

コマンド

bash
1# ビルド
2./gradlew :libs:idp-server-platform:compileJava
3
4# テスト
5cd e2e && npm test -- integration/ida/

トラブルシューティング

スキーマ検証失敗

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

型エラー

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

フォーマット検証失敗

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

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

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