In an OpenAPI schema, what is the difference between allOf, anyOf and oneOf?

## The three keywords Each takes an array of subschemas and is a rule about how many of them the instance must satisfy. - **`allOf`** — the value must validate against *all* subschemas. Logical AND, an intersection of constraints. - **`anyOf`** — the value must validate against *at least one*. Logical OR; matching several is fine. - **`oneOf`** — the value must validate against *exactly one*. Exclusive OR; matching two or more is a validation **failure**. A fourth, `not`, negates a single subschema: the value must *not* validate against it. ## allOf: composition, not inheritance `allOf` is what people reach for to express "a Dog is an Animal plus these extra fields": ``` Dog: allOf: - $ref: '#/components/schemas/Animal' - type: object properties: breed: { type: string } required: [breed] ``` Read precisely, this says nothing about inheritance — it says the instance must satisfy both constraint sets simultaneously. That distinction matters because of the classic footgun: putting `additionalProperties: false` inside one branch. Each subschema is evaluated independently and only sees the properties *it* declares, so the branch that knows about `breed` rejects `name` inherited from `Animal`, and nothing validates. If you need strictness with composition, apply it in a single flattened schema rather than inside an `allOf` branch. Code generators, by convention, do treat a single-`$ref`-plus-object `allOf` as inheritance and emit `class Dog extends Animal`. That is generator convention, not specification semantics. ## oneOf: real alternatives `oneOf` is the right keyword when a payload is one of several distinct shapes: ``` PaymentMethod: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankTransfer' ``` Generators turn this into a union, a sealed class hierarchy, or a wrapper type, depending on the target language. The exclusivity is where documents break. Suppose `CardPayment` and `BankTransfer` are both `type: object` with all-optional properties and no `additionalProperties` restriction. Then `{"last4": "4242"}` validates against both — because a JSON object with an unknown-but-permitted extra property satisfies a permissive object schema — and `oneOf` fails on "more than one matched". The fix is to make the branches genuinely disjoint: give each a `required` discriminating property, often with a single-value `enum` or `const`, so exactly one can ever match. ## anyOf: the permissive union `anyOf` accepts overlap. Use it when the alternatives are not mutually exclusive by nature — "either an email-shaped string or a phone-shaped string, and something might qualify as both" — or when you deliberately want validation to pass on the first success without worrying about exclusivity. Its weakness is tooling. Generators often collapse `anyOf` to a loose type, or to the same union they would build for `oneOf`, losing the distinction. Documentation renderers show it less clearly. Prefer `oneOf` with disjoint branches when you can, because it carries more information. ## Choosing between them A useful decision order: 1. Am I adding constraints to an existing shape? → `allOf`. 2. Are the shapes mutually exclusive alternatives? → `oneOf`, and make the branches provably disjoint. 3. Do the alternatives genuinely overlap? → `anyOf`, and accept weaker codegen. 4. Am I excluding a shape? → `not`, and expect poor tooling support. ## Version notes Swagger 2.0 supported only `allOf`, which is why old documents fake alternatives with a loose object and prose. OpenAPI 3.0 added `oneOf`, `anyOf` and `not`. OpenAPI 3.1, aligned with JSON Schema 2020-12, keeps all four and additionally offers conditional keywords `if`/`then`/`else` and `const`, the last of which is the cleanest way to pin a discriminating property to a single value. `const` is not available in 3.0, where a single-value `enum` is the idiom. ## Nesting and readability All four compose, and a deeply nested `allOf` inside `oneOf` inside `anyOf` quickly becomes unreadable and unsupported by half your toolchain. In production specs, one level of composition is usually enough — flatten aggressively, and if a schema needs three levels of logic to express, the payload design is likely the real problem.