JSON Schema for OpenAPI course

Looking to master JSON Schema for OpenAPI?

A 9+ hour course taught by a member of the JSON Schema Technical Steering Committee

Take the Video Course Also check out our O'Reilly book

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 Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
Kind Applicator
Applies To Any
Base Dialect 2019-09
Changed In None
Introduced In Draft 7
Vocabulary Applicator
Specification https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.section.9.2.2.1
Metaschema https://json-schema.org/draft/2019-09/meta/applicator
Official Tests draft2019-09/if-then-else.json
Default None
Annotation None
Affected By None
Affects
Also See

The if keyword introduces a subschema whose evaluation result restricts instances to validate against the then or else sibling subschemas (if present). Note that the evaluation outcome of this subschema controls which other subschema to apply (if any) but has no direct effect on the overall validation result.

The if , then , and else keywords are equivalent to the ? and : ternary conditional operators found in most programming languages. For example:

bool valid = if_schema ? then_schema : else_schema;

JSON Schema is a constraint-driven language. Therefore, omitting either the then or the else keywords is equivalent to setting the corresponding part of the ternary conditional operation to the boolean true. In other words, undefined consequent or alternative paths lead to success. For example:

// If `then` is missing
bool valid = if_schema ? true : else_schema;
// If `else` is missing
bool valid = if_schema ? then_schema : true;

Examples

A schema that constrains numeric instances to be positive when they are even numbers and negative otherwise Schema 
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "if": { "multipleOf": 2 },
  "then": { "minimum": 0 },
  "else": { "exclusiveMaximum": 0 }
}
Valid An even number value that is positive is valid Instance 
10
Invalid An even number value that is negative is invalid Instance 
-2
Invalid An odd number value that is positive is invalid Instance 
7
Valid An odd number value that is negative is valid Instance 
-3
Valid A non-number value is valid Instance 
"Hello World"
A schema that constrains numeric instances to be positive when they are even numbers Schema 
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "if": { "multipleOf": 2 },
  "then": { "minimum": 0 }
}
Valid An even number value that is positive is valid Instance 
10
Invalid An even number value that is negative is invalid Instance 
-2
Valid An odd number value that is positive is valid Instance 
7
Valid An odd number value that is negative is valid Instance 
-3
A schema that constrains numeric instances to be positive when they are odd numbers Schema 
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "if": { "multipleOf": 2 },
  "else": { "minimum": 0 }
}
Valid An even number value that is positive is valid Instance 
10
Valid An even number value that is negative is valid Instance 
-2
Valid An odd number value that is positive is valid Instance 
7
Invalid An odd number value that is negative is invalid Instance 
-3
A conditional schema that emits an annotation without a consequent or alternative Schema 
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "if": { "items": { "type": "string" } }
}
Valid A value that matches the conditional subschema is valid and receives the annotation Instance 
[ "foo", "bar", "baz" ]
Annotations 
{ "keyword": "/if/items", "instance": "", "value": true }
Valid A value that does not match the conditional subschema is still valid but receives no annotation Instance 
[ 1, 2, 3 ]