Skip to content

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:

BodyoneOfanyOf
{"query":"cat"}204204
{"query":"cat","from":"2026-01-01"}422204
{"size":3}422422

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 meanWrite
Any of these shapes is fine, combinations tooanyOf
Exactly one of these, and a client must be able to tell whichoneOf, with schemas that cannot overlap
All of these at onceallOf

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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish