# 機能設計書：JSONスキーマ検証

## 1. 機能概要

### 1.1 機能名
JSONスキーマ検証（JSON Schema）

### 1.2 機能説明
JSON Schema 仕様に準拠したスキーマをプログラマティックに構築するためのビルダー機能。Object、Array、String、Integer、Number、Boolean の各型に対応し、Fluent API でスキーマ定義を記述できる。AI/LLM との連携や API 仕様定義などに活用される。

### 1.3 関連画面
- なし（バックエンド専用機能）

## 2. 機能詳細

### 2.1 処理フロー

```
[スキーマ定義]
    |
    v
[JsonSchema ファサード]
    |
    v
[JsonSchemaTypeFactory]
    |
    +-- object() -> ObjectType
    +-- array() -> ArrayType
    +-- string() -> StringType
    +-- integer() -> IntegerType
    +-- number() -> NumberType
    +-- boolean() -> BooleanType
    |
    v
[Type インスタンス]
    |
    +-- Fluent API で制約追加
    |
    v
[toArray() / toString()]
    |
    v
[JSON Schema 配列/文字列]
```

### 2.2 クラス構成

| クラス名 | 役割 |
|---------|------|
| JsonSchema | ファサード・静的アクセス |
| JsonSchemaTypeFactory | 型ファクトリー |
| Type | 型の基底クラス |
| ObjectType | オブジェクト型 |
| ArrayType | 配列型 |
| StringType | 文字列型 |
| IntegerType | 整数型 |
| NumberType | 数値型 |
| BooleanType | 真偽値型 |
| Serializer | スキーマシリアライズ |

### 2.3 主要メソッド

#### JsonSchema（ファサード）

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `object()` | オブジェクト型作成 | `$properties` | `ObjectType` |
| `array()` | 配列型作成 | - | `ArrayType` |
| `string()` | 文字列型作成 | - | `StringType` |
| `integer()` | 整数型作成 | - | `IntegerType` |
| `number()` | 数値型作成 | - | `NumberType` |
| `boolean()` | 真偽値型作成 | - | `BooleanType` |

#### Type（基底クラス）

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `required()` | 必須指定 | `$required` | `$this` |
| `nullable()` | null許容指定 | `$nullable` | `$this` |
| `title()` | タイトル設定 | `$value` | `$this` |
| `description()` | 説明設定 | `$value` | `$this` |
| `enum()` | 列挙値制限 | `$values` | `$this` |
| `toArray()` | 配列に変換 | - | `array` |
| `toString()` | JSON文字列に変換 | - | `string` |

#### ObjectType

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `__construct()` | プロパティ指定で作成 | `$properties` | - |
| `withoutAdditionalProperties()` | 追加プロパティ禁止 | - | `$this` |
| `default()` | デフォルト値設定 | `$value` | `$this` |

#### ArrayType

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `items()` | 要素の型指定 | `$type` | `$this` |
| `minItems()` | 最小要素数 | `$value` | `$this` |
| `maxItems()` | 最大要素数 | `$value` | `$this` |
| `uniqueItems()` | 一意性制約 | - | `$this` |

#### StringType

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `minLength()` | 最小文字数 | `$value` | `$this` |
| `maxLength()` | 最大文字数 | `$value` | `$this` |
| `pattern()` | 正規表現パターン | `$pattern` | `$this` |
| `format()` | フォーマット指定 | `$format` | `$this` |

#### IntegerType / NumberType

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `minimum()` | 最小値 | `$value` | `$this` |
| `maximum()` | 最大値 | `$value` | `$this` |
| `exclusiveMinimum()` | 排他的最小値 | `$value` | `$this` |
| `exclusiveMaximum()` | 排他的最大値 | `$value` | `$this` |
| `multipleOf()` | 倍数制約 | `$value` | `$this` |

### 2.4 ビジネスルール

1. **Fluent API**
   - 各メソッドは `$this` を返却
   - メソッドチェーンでスキーマ定義可能

2. **必須指定**
   - `required()` でプロパティを必須に
   - ObjectType の properties に含める

3. **列挙値**
   - `enum()` で許容値を制限
   - BackedEnum クラスも指定可能

4. **シリアライズ**
   - `toArray()` で JSON Schema 形式の配列
   - `toString()` で JSON 文字列

## 3. 入出力仕様

### 3.1 入力

| 項目 | 型 | 説明 |
|-----|-----|------|
| properties | `array<string, Type>` | オブジェクトのプロパティ定義 |
| constraints | various | 各種制約（min, max, pattern等） |

### 3.2 出力

| 項目 | 型 | 説明 |
|-----|-----|------|
| schema | `array` | JSON Schema 形式の配列 |
| json | `string` | JSON Schema 文字列 |

## 4. 依存関係

### 4.1 内部依存

| パッケージ | 用途 |
|-----------|------|
| なし | 外部依存なし |

### 4.2 外部依存

| パッケージ | 用途 |
|-----------|------|
| なし | 外部依存なし |

## 5. エラー処理

| エラー種別 | 発生条件 | 処理内容 |
|-----------|---------|---------|
| InvalidArgumentException | enum に無効なクラス指定 | 例外スロー |

## 6. コードリーディングガイド

### 6.1 推奨読解順序

1. **JsonSchema ファサード** (`JsonSchema/JsonSchema.php`)
   - **9-15行目**: PHPDoc による静的メソッド定義
   - **21-24行目**: `__callStatic()` - ファクトリーへの委譲

2. **JsonSchemaTypeFactory** (`JsonSchema/JsonSchemaTypeFactory.php`)
   - **15-22行目**: `object()` - ObjectType 作成
   - **27-30行目**: `array()` - ArrayType 作成
   - **35-38行目**: `string()` - StringType 作成
   - **43-46行目**: `integer()` - IntegerType 作成
   - **51-54行目**: `number()` - NumberType 作成
   - **59-62行目**: `boolean()` - BooleanType 作成

3. **Type 基底クラス** (`JsonSchema/Types/Type.php`)
   - **10-11行目**: クラス定義
   - **15-42行目**: プロパティ（required, title, description, default, enum, nullable）
   - **47-54行目**: `required()` - 必須設定
   - **59-66行目**: `nullable()` - null許容設定
   - **71-76行目**: `title()` - タイトル設定
   - **81-86行目**: `description()` - 説明設定
   - **95-109行目**: `enum()` - 列挙値設定（BackedEnum対応）
   - **116-119行目**: `toArray()` - シリアライズ
   - **124-127行目**: `toString()` - JSON変換

4. **ObjectType** (`JsonSchema/Types/ObjectType.php`)
   - **5-6行目**: Type を継承
   - **10行目**: additionalProperties プロパティ
   - **17-20行目**: コンストラクタ - プロパティ定義受け取り
   - **25-30行目**: `withoutAdditionalProperties()` - 追加プロパティ禁止
   - **37-42行目**: `default()` - デフォルト値

### 6.2 プログラム呼び出し階層図

```
JsonSchema::object([...])
└── JsonSchema::__callStatic('object', [[...]])
    └── JsonSchemaTypeFactory::object([...])
        └── new ObjectType([...])

$type->required()->description('...')
├── Type::required() -> $this
└── Type::description() -> $this

$type->toArray()
└── Serializer::serialize($type)
    └── [JSON Schema 形式の配列]
```

### 6.3 データフロー図

```
[スキーマ定義コード]
    |
    v
[JsonSchema ファサード]
    |
    +-- __callStatic() で JsonSchemaTypeFactory に委譲
    |
    v
[Type インスタンス]
    |
    +-- プロパティに制約を設定
    +-- Fluent API でチェーン呼び出し
    |
    v
[toArray() / toString()]
    |
    +-- Serializer でシリアライズ
    |
    v
[JSON Schema 出力]
```

### 6.4 読解のコツ

- **静的ファサード**: `__callStatic()` で Factory に委譲
- **継承構造**: すべての型は `Type` を継承
- **Fluent パターン**: すべてのメソッドが `$this` を返却
- **BackedEnum対応**: `enum()` で PHP Enum を直接使用可能

### 6.5 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|------------|------|------|
| `src/Illuminate/JsonSchema/JsonSchema.php` | Facade | 静的アクセス |
| `src/Illuminate/JsonSchema/JsonSchemaTypeFactory.php` | Factory | 型ファクトリー |
| `src/Illuminate/JsonSchema/Serializer.php` | Serializer | シリアライズ |
| `src/Illuminate/JsonSchema/Types/Type.php` | Type | 基底型クラス |
| `src/Illuminate/JsonSchema/Types/ObjectType.php` | Type | オブジェクト型 |
| `src/Illuminate/JsonSchema/Types/ArrayType.php` | Type | 配列型 |
| `src/Illuminate/JsonSchema/Types/StringType.php` | Type | 文字列型 |
| `src/Illuminate/JsonSchema/Types/IntegerType.php` | Type | 整数型 |
| `src/Illuminate/JsonSchema/Types/NumberType.php` | Type | 数値型 |
| `src/Illuminate/JsonSchema/Types/BooleanType.php` | Type | 真偽値型 |
| `src/Illuminate/Contracts/JsonSchema/JsonSchema.php` | Contract | インターフェース |

## 7. 使用例

```php
use Illuminate\JsonSchema\JsonSchema;

// シンプルなオブジェクトスキーマ
$schema = JsonSchema::object([
    'name' => JsonSchema::string()->required(),
    'email' => JsonSchema::string()->required()->format('email'),
    'age' => JsonSchema::integer()->minimum(0)->maximum(150),
]);

// 配列スキーマ
$schema = JsonSchema::array()
    ->items(JsonSchema::string())
    ->minItems(1)
    ->maxItems(10)
    ->uniqueItems();

// ネストしたスキーマ
$schema = JsonSchema::object([
    'user' => JsonSchema::object([
        'id' => JsonSchema::integer()->required(),
        'profile' => JsonSchema::object([
            'bio' => JsonSchema::string()->maxLength(500),
            'avatar' => JsonSchema::string()->format('uri'),
        ]),
    ])->withoutAdditionalProperties(),
    'tags' => JsonSchema::array()->items(JsonSchema::string()),
]);

// Enum 使用
enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

$schema = JsonSchema::object([
    'status' => JsonSchema::string()->enum(Status::class)->required(),
]);

// 説明付き
$schema = JsonSchema::object([
    'price' => JsonSchema::number()
        ->title('商品価格')
        ->description('税込価格（円）')
        ->minimum(0)
        ->required(),
]);

// JSON Schema 出力
$array = $schema->toArray();
$json = $schema->toString();
```

## 8. 出力例

```json
{
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "email": {
            "type": "string",
            "format": "email"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        }
    },
    "required": ["name", "email"]
}
```

## 9. 改版履歴

| バージョン | 日付 | 変更内容 |
|-----------|------|---------|
| 1.0.0 | - | 初版作成 |
