oneOf, allOf, anyOf: composition and inheritance in OpenAPI

oneOf, anyOf, and allOf are keywords in the JSON Schema specification used to define composite data structures. They are essentially logical operators applied to data validation. Apidog fully supports these JSON Schema features, helping you build more accurate API documentation and data validation rules.

Basic Concepts

allOf

allOf means that data must simultaneously satisfy all subschema conditions, equivalent to the AND operation in logical operations. Like the expression "both... and..." in everyday language, all conditions must be met simultaneously for validation to pass.

anyOf

oneOf

Logic Comparison Table

Keyword	Logic Operation	Condition Requirement	Typical Use Case
`allOf`	AND	Must satisfy all conditions simultaneously	Inheritance, extension
`anyOf`	OR	Must satisfy at least one condition	Optional combinations
`oneOf`	XOR	Must satisfy exactly one condition	Mutually exclusive choices

Usage in Apidog

1. Using the Visual Editor

Step 1: Create Data Schemas

In your project, click "Schemas", then "New Schema"

Step 2: Add Schema Composition

In the data schema editing panel, when selecting the type, click "Schema Composition" and choose oneOf, anyOf, or allOf. Define specific data structures for each subschema.

2. Using JSON Schema Code Editor

You can also directly edit JSON Schema code in the data schema editing panel to define these logical composition patterns.

Application in API Documentation

Request Parameter Definition

When defining endpoint request parameters, you can use these composition patterns to describe complex parameter structures:

Enter the API editing page.

In the "Request Parameters" section, select Body and choose JSON type.

In the data structure, click "Reference Schema", or select the appropriate "Schema Composition" based on business logic, or define custom JSON Schema.

Response Data Definition

Similarly, you can use these schema composition in response data:

In the "Response" section, add response examples.

Use schema composition to describe different response formats.

Practical Usage Examples

allOf Example (AND Operation)

Using allOf allows you to combine multiple data schemas together, requiring data to satisfy all conditions simultaneously. This is like saying "user information must include basic information AND contact information":

{
  "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"]
    }
  ]
}

Result: The final data must contain id, name, and email fields, with phone being optional. All constraints from subschemas are merged and executed, as shown below:

anyOf Example (OR Operation)

Using anyOf provides multiple optional validation paths - users can choose any one or multiple methods. This is like saying "users can log in through username/password OR email/password OR phone/verification code":

{
  "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"]
        }
      ]
    }
  }
}

Result: Users can provide information for any one or multiple login methods, as long as at least one method satisfies the validation requirements, as shown below:

oneOf Example (XOR Operation)

Using oneOf ensures that users can only choose one payment method and cannot provide multiple methods simultaneously. This is like saying "payment method must be credit card XOR PayPal XOR bank transfer - exactly one of these options":

{
  "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
        }
      ]
    }
  }
}

Result: Users must choose exactly one payment method - they cannot provide multiple methods simultaneously, nor can they provide none, as shown below:

When choosing composition patterns, first clarify your business logic:

Need to combine/inherit multiple schemas → Use allOf (AND operation)

Need flexible optional combinations → Use anyOf (OR operation)

Need strict mutually exclusive choices → Use oneOf (XOR operation)

oneOf, allOf, anyOf: composition and inheritance in OpenAPI

Basic Concepts#

Logic Comparison Table#

Usage in Apidog#

1. Using the Visual Editor#

2. Using JSON Schema Code Editor#

Application in API Documentation#

Request Parameter Definition#

Response Data Definition#

Practical Usage Examples#

allOf Example (AND Operation)#

anyOf Example (OR Operation)#

oneOf Example (XOR Operation)#