oneOf — Exclusive Schema Matching

oneOf — Exactly One Schema Must Match

The oneOf keyword validates that a value matches exactly one of the provided sub-schemas. If the value matches zero schemas or more than one schema, validation fails. This creates a mutually exclusive choice — a discriminated union.

Basic Syntax

{
  "oneOf": [
    { "type": "string" },
    { "type": "integer" }
  ]
}

This accepts strings or integers, but not values that could be both. Since strings and integers are inherently different types, this behaves like anyOf in practice. The power of oneOf shows when sub-schemas can overlap.

How the Example Schema Works

The schema models a payment method using a discriminated union pattern:

1. Credit card — requires method: "credit_card", a cardNumber (13-19 digits), and an expiry date (MM/YY format).
2. Bank transfer — requires method: "bank_transfer" and an iban (International Bank Account Number).
3. PayPal — requires method: "paypal" and an email address.

Each sub-schema uses const on the method field as a discriminator — a fixed value that identifies which variant applies. The additionalProperties: false in each sub-schema ensures no cross-contamination between variants.

The test data provides credit card details with method: "credit_card", which matches only the first sub-schema. The other two schemas fail (wrong method value), so exactly one match — validation passes.

The Discriminator Pattern

The most robust way to use oneOf is with a discriminator field:

{
  "oneOf": [
    { "properties": { "type": { "const": "A" } }, ... },
    { "properties": { "type": { "const": "B" } }, ... }
  ]
}

The const on the discriminator ensures exactly one sub-schema can match for any valid input. Without a discriminator, you risk overlapping schemas where a value accidentally matches multiple alternatives.

Failure Modes

oneOf fails in two distinct ways:

• Zero matches: The value does not satisfy any sub-schema. Error: "value did not match any of the alternatives."
• Multiple matches: The value satisfies two or more sub-schemas. Error: "value matched more than one alternative."

The multiple-match failure is unique to oneOf and does not occur with anyOf. It catches schema design errors where your alternatives are not truly mutually exclusive.

Performance Note

Validators must evaluate all sub-schemas (they cannot short-circuit after finding one match) because they need to confirm that exactly one matches. For schemas with many alternatives, consider using if/then/else chains for better performance.