no-unnecessary-combinator

Schema combinators (allOf, anyOf, oneOf) with only a single item are unnecessary and should be replaced with the item directly. These single-item combinators add no functional benefit while reducing clarity and potentially affecting performance.

This rule helps identify schemas that can be simplified by removing redundant combinator wrappers.

Why did this violation appear?

Your schema contains a combinator (allOf, anyOf, or oneOf) that only has one item in its array. Since combinators are designed to combine multiple schemas, having only one item makes the combinator pointless.

What is this rule checking for?

The rule examines all schemas in OpenAPI 3.x specifications and identifies any schema that uses:

• allOf with exactly one item
• anyOf with exactly one item
• oneOf with exactly one item

Bad example

components:
  schemas:
    User:
      allOf:
        - $ref: "#/components/schemas/Person"  # Only one item - unnecessary
    Product:
      anyOf:
        - type: string  # Only one item - unnecessary
    Status:
      oneOf:
        - enum: [active, inactive]  # Only one item - unnecessary

Good Example

components:
  schemas:
    User:
      $ref: "#/components/schemas/Person"  # Direct reference
    Product:
      type: string  # Direct type
    Status:
      enum: [active, inactive]  # Direct enum

    # Valid multi-item combinators
    Employee:
      allOf:
        - $ref: "#/components/schemas/Person"
        - type: object
          properties:
            employeeId:
              type: string

How do I fix this violation?

Replace the single-item combinator with its content directly:

1. For allOf with one item: Use the single schema directly
2. For anyOf with one item: Use the single schema directly
3. For oneOf with one item: Use the single schema directly

Benefits of fixing:

• Improved clarity: Direct schemas are easier to understand
• Better performance: Eliminates unnecessary validation layers
• Tool compatibility: Some tools handle direct schemas better than single-item combinators
• Simpler maintenance: Less nesting makes schemas easier to modify