oneOf vs anyOf in OpenAPI: the one payload that tells them apart
Last checked and updated
oneOf is valid when exactly one of the listed schemas matches. anyOf is valid when one or more match. For a value that fits one schema, or none, they behave the same. They differ on exactly one kind of value: one that fits two schemas. oneOf refuses it, anyOf accepts it.
The same schemas under both
A search accepts a text filter, a date filter, or (under anyOf) both:
TextFilter:
type: object
required: [query]
properties:
query:
type: string
DateFilter:
type: object
required: [from]
properties:
from:
type: string
format: date
One operation lists them under oneOf, another under anyOf. A mock server generated from the file answers:
| Body | oneOf | anyOf |
|---|---|---|
{"query":"cat"} | 204 | 204 |
{"query":"cat","from":"2026-01-01"} | 422 | 204 |
{"size":3} | 422 | 422 |
The middle row is the whole difference. Under oneOf:
$ curl -X POST http://127.0.0.1:4631/filters-oneof \
-H 'content-type: application/json' -d '{"query":"cat","from":"2026-01-01"}'
HTTP/1.1 422 Unprocessable Entity
{"errors":[{"in":"body","pointer":"","message":"must match exactly one schema in oneOf"}],
"type":"https://apigit.com/mock/problems/invalid-request",
"title":"The request does not match the API description","status":422, ...}
Under anyOf the same body is accepted (204 No Content). A body that fits neither is refused by both; anyOf then lists why each schema failed:
{"errors":[
{"in":"body","pointer":"","message":"must have required property 'query'"},
{"in":"body","pointer":"","message":"must have required property 'from'"},
{"in":"body","pointer":"","message":"must match a schema in anyOf"}],
"type":"https://apigit.com/mock/problems/invalid-request",
"title":"The request does not match the API description","status":422, ...}
Why the overlap happens
Neither schema forbids the other's property: an object with query and from has everything TextFilter requires and everything DateFilter requires. Object schemas are open by default, so "has a query" does not mean "has only a query".
Choosing
| You mean | Write |
|---|---|
| Any of these shapes is fine, combinations too | anyOf |
| Exactly one of these, and a client must be able to tell which | oneOf, with schemas that cannot overlap |
| All of these at once | allOf |
To make oneOf schemas exclusive, give each a property with a fixed value (const, or a one-value enum in OpenAPI 3.0) and add a discriminator, or close them with additionalProperties: false. If you do neither, oneOf fails on input you meant to accept: see "must match exactly one schema in oneOf".
What generators do with them
Validation is not the only reader. A code generator that turns oneOf into a union type needs a way to pick the case from the data: without a discriminator it can only try each schema in turn. What a generator makes of anyOf varies from tool to tool, so check the output of the one you use. If generated clients matter, exclusive oneOf schemas with a discriminator are the description that leaves the least to interpretation.
All three keywords side by side: oneOf, allOf and anyOf in OpenAPI.