Reference

Schema Composition

JSON Schema includes a few keywords for combining schemas together. Note that this doesn't necessarily mean combining schemas from multiple files or JSON trees, though these facilities help to enable that and are described in Structuring a complex schema. Combining schemas may be as simple as allowing a value to be validated against multiple criteria at the same time.

These keywords correspond to well known boolean algebra concepts like AND, OR, XOR, and NOT. You can often use these keywords to express complex constraints that can't otherwise be expressed with standard JSON Schema keywords.

The keywords used to combine schemas are:

  • allOf: (AND) Must be valid against all of the subschemas
  • anyOf: (OR) Must be valid against any of the subschemas
  • oneOf: (XOR) Must be valid against exactly one of the subschemas

All of these keywords must be set to an array, where each item is a schema. Be careful with recursive schemas as they can exponentially increase processing times.

In addition, there is:

  • not: (NOT) Must not be valid against the given schema

allOf

To validate against allOf, the given data must be valid against all of the given subschemas.

schema
{ "allOf": [ { "type": "string" }, { "maxLength": 5 } ]}
data
"short"
compliant to schema
data
"too long"
not compliant to schema

allOf can not be used to "extend" a schema to add more details to it in the sense of object-oriented inheritance. Instances must independently be valid against "all of" the schemas in the allOf. See the section on Extending Closed Schemas for more information.

anyOf

To validate against anyOf, the given data must be valid against any (one or more) of the given subschemas.

schema
{ "anyOf": [ { "type": "string", "maxLength": 5 }, { "type": "number", "minimum": 0 } ]}
data
"short"
compliant to schema
data
"too long"
not compliant to schema
data
12
compliant to schema
data
-5
not compliant to schema

oneOf

To validate against oneOf, the given data must be valid against exactly one of the given subschemas.

schema
{ "oneOf": [ { "type": "number", "multipleOf": 5 }, { "type": "number", "multipleOf": 3 } ]}
data
10
compliant to schema
data
9
compliant to schema

Not a multiple of either 5 or 3.

data
2
not compliant to schema

Multiple of both 5 and 3 is rejected.

data
15
not compliant to schema
Careful consideration should be taken when using oneOf entries as the nature of it requires verification of every sub-schema which can lead to increased processing times. Prefer anyOf where possible.

not

The not keyword declares that an instance validates if it doesn't validate against the given subschema.

For example, the following schema validates against anything that is not a string:

schema
{ "not": { "type": "string" } }
data
42
compliant to schema
data
{ "key": "value" }
compliant to schema
data
"I am a string"
not compliant to schema

Properties of Schema Composition

Illogical Schemas

Note that it's quite easy to create schemas that are logical impossibilities with these keywords. The following example creates a schema that won't validate against anything (since something may not be both a string and a number at the same time):

schema
{ "allOf": [ { "type": "string" }, { "type": "number" } ]}
data
"No way"
not compliant to schema
data
-1
not compliant to schema

Factoring Schemas

Note that it's possible to "factor" out the common parts of the subschemas. The following two schemas are equivalent.

schema
{ "oneOf": [ { "type": "number", "multipleOf": 5 }, { "type": "number", "multipleOf": 3 } ]}
schema
{ "type": "number", "oneOf": [ { "multipleOf": 5 }, { "multipleOf": 3 } ]}

Need Help?

Did you find these docs helpful?

Help us make our docs great!

At JSON Schema, we value docs contributions as much as every other type of contribution!

Still Need Help?

Learning JSON Schema is often confusing, but don't worry, we are here to help!.