oneOf : Array<Schema>

oneOf

Array<Schema>

An instance validates successfully against this keyword if it validates successfully against exactly one schema defined by this keyword’s value.

Value This keyword must be set to a non-empty array, where each item is a valid JSON Schema
Kind Applicator
Applies To Any
Dialect 2020-12
Changed In None
Introduced In Draft 4
Vocabulary Applicator
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.2.1.3
Metaschema https://json-schema.org/draft/2020-12/meta/applicator
Official Tests draft2020-12/oneOf.json
Default As if it was set to the (invalid) value: []
Annotation None
Affected By None
Affects None
Also See

The oneOf keyword allows you to specify that exactly one of the provided subschemas must validate successfully against a given instance. It ensures that the instance validates against one and only one of the defined subschemas within the oneOf array. This behavior is akin to a logical “XOR” (exclusive OR) operation, where only one condition needs to be met for validation to pass.

Examples

Schema with 'oneOf' keyword containing only one subschema Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "foo": { "type": "string" }
      },
      "required": [ "foo" ]
    }
  ]
}
Valid An instance conforming to only one subschema of 'oneOf' is valid Instance 
{ "foo": "foo" }
Invalid The value of 'foo' must be a string Instance 
{ "foo": [ "foo" ] }
Schema with 'oneOf' keyword containing multiple subschemas Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "oneOf": [
    {
      "properties": {
        "foo": { "type": "string" }
      },
      "required": [ "foo" ]
    },
    {
      "properties": {
        "bar": { "type": "number" }
      },
      "required": [ "bar" ]
    }
  ]
}
Valid An instance conforming to only one of the subschemas of 'oneOf' is valid Instance 
{ "foo": "foo" }
Invalid An instance that does not conform to any of the subschemas of 'oneOf' is invalid Instance 
{ "foo": 33, "bar": "bar" }
Invalid An instance conforming to all the subschemas of 'oneOf' is also invalid Instance 
{ "foo": "foo", "bar": 33 }
Schema with 'oneOf' keyword containing some boolean subschemas Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    false,
    {
      "properties": {
        "foo": { "type": "string" }
      },
      "required": [ "foo" ]
    }
  ]
}
Valid An instance conforming to the second subschema of 'oneOf' is valid Instance 
{ "foo": "foo" }
Invalid An instance not conforming to the second subschema of 'oneOf' is invalid Instance 
{ "foo": false }
Schema with 'oneOf' keyword containing some boolean subschemas Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    true,
    {
      "properties": {
        "foo": { "type": "string" }
      },
      "required": [ "foo" ]
    }
  ]
}
Invalid An instance conforming to the second subschema of 'oneOf' is invalid Instance 
{ "foo": "foo" }
Valid An instance not conforming to the second subschema of 'oneOf' is valid Instance 
{ "foo": true }
  • Remember, if any subschema within the oneOf keyword passes validation or has a boolean true value, the all the other subschemas within oneOf must fail the validation for the overall validation of the oneOf keyword to be true.
Schema with nested 'oneOf' Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "oneOf": [
        { "type": "number" }
      ]
    },
    {
      "oneOf": [
        { "type": "string" }
      ]
    }
  ]
}
Valid An instance conforming to only the first subschema within 'oneOf' is valid Instance 
25
Valid An instance conforming to only the second subschema within 'oneOf' is valid Instance 
"25"
Invalid An instance not conforming to any of the subschemas within 'oneOf' is invalid Instance 
[ "25" ]