Skip to content

"must match exactly one schema in oneOf": what it means and how to fix it

Last checked and updated

oneOf is satisfied when a value matches exactly one of the listed schemas. The message "must match exactly one schema in oneOf" (the wording of the Ajv validator) therefore covers two different failures: the value matched none of them, or it matched more than one. The rest of the error list tells you which.

Case 1: it matched none

The error comes with the reasons each schema refused the value:

$ curl -X POST http://127.0.0.1:4611/payments \
    -H 'content-type: application/json' -d '{"type":"card"}'
HTTP/1.1 422 Unprocessable Entity

{"errors":[
  {"in":"body","pointer":"","message":"must have required property 'number'"},
  {"in":"body","pointer":"","message":"must have required property 'iban'"},
  {"in":"body","pointer":"/type","message":"must be equal to constant"},
  {"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, ...}

Read the other lines: the card schema wants number, the bank transfer schema wants iban and another type. The payload is simply incomplete. Fix the payload, not the schema.

Case 2: it matched more than one

Here the message stands alone, because no schema refused the value:

$ curl -X POST http://127.0.0.1:4612/payments -H 'content-type: application/json' \
    -d '{"type":"card","number":"4242","iban":"DE00"}'
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, ...}

The schemas behind this answer:

PaymentMethod:
  oneOf:
    - $ref: "#/components/schemas/Card"
    - $ref: "#/components/schemas/BankTransfer"
Card:
  type: object
  properties:
    type:
      type: string
    number:
      type: string
BankTransfer:
  type: object
  properties:
    type:
      type: string
    iban:
      type: string

Nothing is required and nothing is forbidden, so every object matches both. Even {} fails, for the same reason. A linter does not see this: the file is a valid OpenAPI document (apigit lint reports no finding on these schemas). The problem only shows when a payload is validated.

The fixes

Make the schemas exclusive. Any one of these is enough; the first two together are the usual choice.

  1. Require what identifies each case. required: [type, number] on Card, required: [type, iban] on BankTransfer.
  2. Fix a distinguishing value. type: { const: card } and type: { const: bank_transfer } (in OpenAPI 3.0: enum: [card]). Add a discriminator so generators and documentation know about it too.
  3. Close the objects. additionalProperties: false on each schema makes a card with an iban fail the card schema. See additionalProperties for what that costs.

With fixes 1 and 2 the same mock answers 201 Created to {"type":"card","number":"4242"}.

Or it should have been anyOf

If a value may legitimately fit several schemas, for example a search filter that accepts a text query, a date range or both, oneOf is the wrong keyword. anyOf needs at least one match and does not mind two.

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