"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.
- Require what identifies each case.
required: [type, number]onCard,required: [type, iban]onBankTransfer. - Fix a distinguishing value.
type: { const: card }andtype: { const: bank_transfer }(in OpenAPI 3.0:enum: [card]). Add a discriminator so generators and documentation know about it too. - Close the objects.
additionalProperties: falseon each schema makes a card with anibanfail 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.