if : Schema

if

Schema

This keyword declares a condition based on the validation result of the given schema.

Value This keyword must be set to a valid JSON Schema
Kind Applicator
Applies To Any
Dialect 2020-12
Changed In None
Introduced In Draft 7
Vocabulary Applicator
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-10.2.2.1
Metaschema https://json-schema.org/draft/2020-12/meta/applicator
Official Tests draft2020-12/if-then-else.json
Default None
Annotation None
Affected By None
Affects
Also See

The if keyword is used to conditionally apply a subschema based on whether a certain condition is met. It allows you to define different validation rules depending on whether an instance satisfies a condition or not. The validation outcome of this keyword’s subschema has no direct effect on the overall validation result. Rather, it controls which of the then or else keywords are evaluated.

  • If an instance passes the validation against the if subschema, then it must also be validated against the then subschema, if present.
  • If an instance fails the validation against the if subschema, then it must also be validated against the else subschema, if present.
  • This keyword is meaningless without then and else.
  • The annotations are collected from this keyword’s subschema in the usual way, irrespective of whether then and else are present or not.

Examples

Schema with 'if', 'then' and 'else' keyword Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "role": { "enum": [ "HOD", "professor" ] },
    "HOD_Id": { "type": "integer" },
    "professor_Id": { "type": "integer" }
  },
  "if": {
    "properties":
      { "role": { "const": "HOD" }
    }
  },
  "then": { "required": [ "HOD_Id" ] },
  "else": { "required": [ "professor_Id" ] }
}
Valid An instance adhering to the schema is valid Instance
{ "name": "John Doe", "role": "HOD", "HOD_Id": 2844 }
Invalid 'professor_Id' is required when the value of role is 'professor' Instance
{ "role": "professor" }
Valid Any object instance without the 'role' property is valid Instance
{ "professor_Id": 2899, "HOD_Id": 2844 }
Invalid the value of 'HOD_Id' must be a string Instance
{ "name": "John Doe", "role": "HOD", "HOD_Id": "2844" }
Schema with 'if' and 'then' without 'else' Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "if": {
    "properties":
      { "foo": { "const": "foo" }
    }
  },
  "then": { "required": [ "bar" ] }
}
Valid An object instance conforming to the 'if' and 'then' subschemas is valid Instance
{ "foo": "foo", "bar": "bar" }
Invalid If an instance conforms to the 'if' subschema, then it must also conform to the 'then' subschema Instance
{ "foo": "foo" }
Valid An object instance not conforming to the 'if' subschemas is always valid Instance
{ "foo": "not foo", "baz": "baz" }
Schema with 'if' and 'else' without 'then' Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "if": {
    "properties":
      { "foo": { "const": "foo" }
    }
  },
  "else": { "required": [ "baz" ] }
}
Valid An object instance that does not conform to the 'if' subschema but conforms to the 'else' subschemas is valid Instance
{ "foo": "not foo", "baz": "baz" }
Invalid If an instance does not conform to the 'if' subschema, then it must conform to the 'else' subschema Instance
{ "foo": "not foo" }
Valid An object instance conforming to the 'if' subschemas is always valid Instance
{ "foo": "foo", "baz": "baz" }
  • Note: If an instance passes the if subschema and the then subschema is not present, then the then subschema behaves as a boolean true schema. Similarly, if an instance fails the if subschema and the else subschema is not present, then the else subschema behaves as a boolean true schema.
Schema with 'if' without 'then' and 'else' Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "if": {
    "properties": {
      "foo": {
        "title": "This is foo!",
        "const": "foo"
      }
    }
  }
}
Valid Instance
{ "foo": "foo" }
Annotations
{ "keyword": "/if/properties", "instance": "", "value": [ "foo" ] }
{ "keyword": "/if/properties/foo/title", "instance": "", "value": "This is foo!" }
  • Here, the annotations are collected from if’s subschema in the usual way, irrespective of whether then and else are present or not.