if : Schema

if

Schema

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

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

  • The value of this keyword must be a valid JSON Schema.
  • 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" ] }
}
An instance adhering to the schema is valid Instance 
{ "name": "John Doe", "role": "HOD", "HOD_Id": 2844 }
'professor_Id' is required when the value of role is 'professor' Instance 
{ "role": "professor" }
Any object instance without the 'role' property is valid Instance 
{ "professor_Id": 2899, "HOD_Id": 2844 }
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" ] }
}
An object instance conforming to the 'if' and 'then' subschemas is valid Instance 
{ "foo": "foo", "bar": "bar" }
If an instance conforms to the 'if' subschema, then it must also conform to the 'then' subschema Instance 
{ "foo": "foo" }
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" ] }
}
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" }
If an instance does not conform to the 'if' subschema, then it must conform to the 'else' subschema Instance 
{ "foo": "not foo" }
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"
      }
    }
  }
}
Instance 
{ "foo": "foo" }
Annotations 
[
  // ...
  {
    "valid": true,
    "keywordLocation": "/if/properties",
    "instanceLocation": "",
    "annotation": [ "foo" ]
  },
  {
    "valid": true,
    "keywordLocation": "/if/properties/foo/title",
    "instanceLocation": "",
    "annotation": "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.