DEV Community: Umar Tahir

`allOf` vs `oneOf` vs `anyOf` in OpenAPI (with examples)

Umar Tahir — Tue, 23 Dec 2025 07:20:24 +0000

If you’ve worked with OpenAPI schemas, you’ve probably seen oneOf, anyOf, and allOf and wondered:

“They look similar… so when should I actually use each one?”

Let’s break them down with practical, API-design–focused examples.

`allOf` Composition / Inheritance

Meaning:
👉 The schema must satisfy all listed schemas.

Think of allOf as “AND”.

When to use it

To compose schemas
To model base + extension

Example

InverterCreate:
  allOf:
    - $ref: '#/components/schemas/ApplianceBase'
    - type: object
      properties:
        reverseFlow:
          type: boolean

What this means:
✔ The request must match ApplianceBase
✔ AND it must match other specific fields

This is perfect for:

Base appliance fields (name, location)
Plus type-specific fields

`oneOf` Exactly one schema

Meaning:
👉 The schema must match exactly one of the listed schemas.

Think of oneOf as “XOR”.

When to use it

When schemas are mutually exclusive
When you want strict validation
Often combined with a discriminator

Example

oneOf:
  - $ref: '#/components/schemas/InverterPatch'
  - $ref: '#/components/schemas/EVPatch'
  - $ref: '#/components/schemas/EVCSPatch'

Important detail ⚠️

If a request matches more than one schema, validation fails.

That’s why oneOf + PATCH + overlapping fields can be tricky.

With discriminator (recommended)

discriminator:
  propertyName: type

{
  "type": "inverter",
  "reverseFlow": true
}

The discriminator tells OpenAPI which schema to use, removing ambiguity.

`anyOf` One or more schemas

Meaning:
👉 The schema must match at least one of the listed schemas.

Think of anyOf as “OR”.

When to use it

When schemas overlap
When flexibility is more important than strictness
When multiple schema matches are acceptable

Example

anyOf:
  - $ref: '#/components/schemas/InverterSpecificPatch'
  - $ref: '#/components/schemas/EVSpecificPatch'

This allows requests that:

Match one schema
Match multiple schemas

PATCH + Overlapping Fields: The Key Insight

Consider this PATCH request:

{
  "reverseFlow": true
}

If:

reverseFlow exists in multiple schemas
You’re using oneOf

👉 OpenAPI cannot decide which schema applies
👉 Validation fails unless you use a discriminator

That’s why:

oneOf + PATCH + overlapping fields → discriminator strongly recommended
allOf is great for base + extensions
anyOf is useful when overlap is intentional and acceptable

Quick decision table

Goal	Use
Schema composition / inheritance	`allOf`
Exactly one valid schema	`oneOf`
Flexible matching	`anyOf`
PATCH with overlapping fields	`oneOf` + discriminator or single schema
Strict API contracts	`oneOf`
Simpler client experience	Single schema / `anyOf`

Final takeaway

allOf = build schemas
oneOf = enforce exclusivity
anyOf = allow flexibility
Discriminators exist to remove ambiguity, especially for PATCH requests

If your API has polymorphic resources and partial updates, understanding this distinction is crucial to designing clean, predictable OpenAPI specs.

Understanding oneOf in OpenAPI (Without the Confusion)

Umar Tahir — Tue, 23 Dec 2025 07:00:22 +0000

When designing APIs with OpenAPI, oneOf often looks intimidating. It’s powerful, but easy to misuse especially with PATCH endpoints. Let’s break it down simply.

What is `oneOf`?

In OpenAPI (JSON Schema), oneOf means:

The request body must match exactly one schema from the list.

Not zero.
Not two.
Exactly one.

Example:

schema:
  oneOf:
    - $ref: '#/components/schemas/InverterPatch'
    - $ref: '#/components/schemas/EVPatch'
    - $ref: '#/components/schemas/EVCSPatch'

This tells OpenAPI:

“The payload must conform to exactly one of these schemas.”

Why `oneOf` is tricky with PATCH

PATCH requests are partial updates. Clients often send only a few fields.

Now imagine this payload:

{
  "reverseFlow": true
}

If reverseFlow exists in:

InverterPatch
EVCSPatch

Then this payload matches more than one schema.

🚫 Result: Validation fails, because oneOf requires exactly one match.

Enter the Discriminator

A discriminator solves this ambiguity.

discriminator:
  propertyName: type

Now the client sends:

{
  "type": "inverter",
  "reverseFlow": true
}

OpenAPI immediately knows:

type = inverter
→ use InverterPatch
→ validation succeeds

💡 The discriminator tells OpenAPI which schema to validate against.

When You SHOULD Use `oneOf`

Use oneOf (with a discriminator) when:

You have multiple schemas
Some fields overlap
Clients may send partial updates
You want OpenAPI-level validation, not just backend logic

When You Should NOT Use `oneOf`

Avoid oneOf if:

You don’t need OpenAPI to pick between schemas
Backend already knows the resource type
You’re okay validating type-specific rules at runtime

In those cases, a single PATCH schema with optional fields is simpler and often better.

Key Takeaway

oneOf = exactly one schema must match
Overlapping fields + PATCH = ambiguity
Discriminator resolves ambiguity
Don’t use oneOf unless you actually need schema selection

Used correctly, oneOf makes your API safer and self-documenting. Used incorrectly, it makes PATCH endpoints painful.

DEV Community: Umar Tahir

`allOf` vs `oneOf` vs `anyOf` in OpenAPI (with examples)

allOf Composition / Inheritance

When to use it

Example

oneOf Exactly one schema

When to use it

Example

Important detail ⚠️

With discriminator (recommended)

anyOf One or more schemas

When to use it

Example

PATCH + Overlapping Fields: The Key Insight

Quick decision table

Final takeaway

Understanding oneOf in OpenAPI (Without the Confusion)

What is oneOf?

Why oneOf is tricky with PATCH

Enter the Discriminator

When You SHOULD Use oneOf

When You Should NOT Use oneOf

Key Takeaway

`allOf` Composition / Inheritance

`oneOf` Exactly one schema

`anyOf` One or more schemas

What is `oneOf`?

Why `oneOf` is tricky with PATCH

When You SHOULD Use `oneOf`

When You Should NOT Use `oneOf`