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.

Kind Applicator
Applies To Any
Dialect 2020-12
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
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.

  • The value of this keyword must be a non-empty array.
  • Each item of the array must be a valid JSON Schema.

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" ]
    }
  ]
}
An instance conforming to only one subschema of 'oneOf' is valid Instance 
{ "foo": "foo" }
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" ]
    }
  ]
}
An instance conforming to only one of the subschemas of 'oneOf' is valid Instance 
{ "foo": "foo" }
An instance that does not conform to any of the subschemas of 'oneOf' is invalid Instance 
{ "foo": 33, "bar": "bar" }
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" ]
    }
  ]
}
An instance conforming to the second subschema of 'oneOf' is valid Instance 
{ "foo": "foo" }
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" ]
    }
  ]
}
An instance conforming to the second subschema of 'oneOf' is invalid Instance 
{ "foo": "foo" }
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" }
      ]
    }
  ]
}
An instance conforming to only the first subschema within 'oneOf' is valid Instance 
25
An instance conforming to only the second subschema within 'oneOf' is valid Instance 
"25"
An instance not conforming to any of the subschemas within 'oneOf' is invalid Instance 
[ "25" ]