oneOf、allOf、anyOf

oneOf、anyOf、allOf は、複合データ構造を定義するために使用される JSON Schema 仕様のキーワードです。これらは本質的に、データ検証に適用される論理演算子です。Apidog はこれらの JSON Schema 機能を完全にサポートしており、より正確な API ドキュメントとデータ検証ルールの構築に役立ちます。

基本概念

allOf

allOf は、データがすべてのサブスキーマ条件を同時に満たす必要があることを意味し、論理演算における AND 演算に相当します。日常言語の「...かつ...」という表現と同様に、検証に合格するにはすべての条件を同時に満たす必要があります。

anyOf

oneOf

論理比較表

キーワード	論理演算	条件要件	典型的なユースケース
`allOf`	AND	すべての条件を同時に満たす必要があります	継承、拡張
`anyOf`	OR	少なくとも 1 つの条件を満たす必要があります	任意の組み合わせ
`oneOf`	XOR	正確に 1 つの条件を満たす必要があります	相互排他的な選択肢

Apidog での使用方法

1. ビジュアルエディターを使用する

ステップ 1: データスキーマを作成する

プロジェクトで 「Schemas」 をクリックし、次に 「New Schema」 をクリックします。

ステップ 2: スキーマ合成を追加する

データスキーマ編集パネルで型を選択する際に、「Schema Composition」 をクリックし、oneOf、anyOf、または allOf を選択します。各サブスキーマに対して具体的なデータ構造を定義します。

2. JSON Schema コードエディターを使用する

データスキーマ編集パネルで JSON Schema コードを直接編集し、これらの論理合成パターンを定義することもできます。

API ドキュメントでの適用

リクエストパラメータの定義

エンドポイントのリクエストパラメータを定義する際に、これらの合成パターンを使用して複雑なパラメータ構造を記述できます。

API 編集ページに移動します。

「Request Parameters」 セクションで Body を選択し、JSON 型を選択します。

データ構造で 「Reference Schema」 をクリックするか、ビジネスロジックに基づいて適切な 「Schema Composition」 を選択するか、カスタム JSON Schema を定義します。

レスポンスデータの定義

同様に、レスポンスデータでもこれらのスキーマ合成を使用できます。

「Response」 セクションで、レスポンス例を追加します。

スキーマ合成を使用して、異なるレスポンス形式を記述します。

実用的な使用例

allOf の例（AND 演算）

allOf を使用すると、複数のデータスキーマを組み合わせ、データがすべての条件を同時に満たすことを要求できます。これは、「ユーザー情報には基本情報が含まれている必要がある AND 連絡先情報」と言うようなものです。

{
  "allOf": [
    {
      "description": "Basic user information",
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "description": "Contact information", 
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      },
      "required": ["email"]
    }
  ]
}

結果: 最終データには id、name、email フィールドが含まれている必要があり、phone は任意です。以下に示すように、サブスキーマからのすべての制約がマージされて実行されます。

anyOf の例（OR 演算）

anyOf を使用すると、複数の任意の検証パスを提供できます。ユーザーは任意の 1 つまたは複数の方法を選択できます。これは、「ユーザーはユーザー名/パスワードでログインできる OR メール/パスワード OR 電話番号/認証コード」と言うようなものです。

{
  "type": "object",
  "properties": {
    "login": {
      "anyOf": [
        {
          "description": "Username/password login",
          "properties": {
            "username": { "type": "string" },
            "password": { "type": "string" }
          },
          "required": ["username", "password"]
        },
        {
          "description": "Email/password login",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "password": { "type": "string" }
          },
          "required": ["email", "password"]
        },
        {
          "description": "Phone/verification code login",
          "properties": {
            "phone": { "type": "string" },
            "verifyCode": { "type": "string" }
          },
          "required": ["phone", "verifyCode"]
        }
      ]
    }
  }
}

結果: ユーザーは、少なくとも 1 つの方法が検証要件を満たしている限り、任意の 1 つまたは複数のログイン方法の情報を提供できます。以下に示します。

oneOf の例（XOR 演算）

oneOf を使用すると、ユーザーが 1 つの支払い方法のみを選択でき、複数の方法を同時に提供できないことを保証できます。これは、「支払い方法はクレジットカードである必要がある XOR PayPal XOR 銀行振込 - これらの選択肢のうち正確に 1 つ」と言うようなものです。

{
  "type": "object", 
  "properties": {
    "payment": {
      "oneOf": [
        {
          "description": "Credit card payment",
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"],
          "additionalProperties": false
        },
        {
          "description": "PayPal payment", 
          "type": "object",
          "properties": {
            "type": { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          },
          "required": ["type", "email"],
          "additionalProperties": false
        },
        {
          "description": "Bank transfer",
          "type": "object", 
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "routingNumber": { "type": "string" }
          },
          "required": ["type", "accountNumber", "routingNumber"],
          "additionalProperties": false
        }
      ]
    }
  }
}

結果: ユーザーは正確に 1 つの支払い方法を選択する必要があります。複数の方法を同時に提供することも、何も提供しないこともできません。以下に示します。

ベストプラクティス

合成パターンを選択する際は、まずビジネスロジックを明確にしてください。

複数のスキーマを組み合わせる/継承する必要がある場合 → allOf（AND 演算）を使用します

柔軟な任意の組み合わせが必要な場合 → anyOf（OR 演算）を使用します

厳密な相互排他的な選択肢が必要な場合 → oneOf（XOR 演算）を使用します

oneOf、allOf、anyOf

基本概念#

論理比較表#

Apidog での使用方法#

1. ビジュアルエディターを使用する#

2. JSON Schema コードエディターを使用する#

API ドキュメントでの適用#

リクエストパラメータの定義#

レスポンスデータの定義#

実用的な使用例#

allOf の例（AND 演算）#

anyOf の例（OR 演算）#

oneOf の例（XOR 演算）#

ベストプラクティス#