Schema merging rules - sgpinkus/json-schema GitHub Wiki

THIS WIKI IS OBSOLETE. PLEASE SEE THE NEW JSON-SCHEMA-ORG/JSON-SCHEMA-SPEC REPOSITORY.

---

---

What this page IS NOT

First things first: at this moment, JSON Schema has no schema merging support.

This page is entirely speculative. It does not represent behaviour in any existing specification.

This page is just a list of rules of what JSON Schema merging could be, if it happens one day. And it is not complete.

What this page is

This page defines, keyword by keyword, possible merging rules, starting from the most simple keywords up to the most complex ones.

The two schemas being merged will be referred to as schema1 and schema2.

General rules

The result of merging schema1 and schema2 must be the same as merging schema2 and schema1.

If a keyword is present in schema1 and not in schema2 (or the reverse), then the value of this keyword in the resulting schema will be the same as the value of this keyword in the schema where it is defined.

minItems, minLength, minProperties

Rule

The value of this keyword in the merged schema will be the greater value of both schemas.

Example

schema1:

{
    "minItems": 2
}

schema2:

{
    "minItems": 4
}

Result:

{
    "minItems": 4
}

maxItems, maxLength, maxProperties

Rule

The value of this keyword in the merged schema will be the lower value of both schemas.

Example

schema1:

{
    "maxItems": 2
}

schema2:

{
    "maxItems": 4
}

Result:

{
    "maxItems": 2
}

minimum and exclusiveMinimum

Rule

The resulting value of the minimum keyword in the merged schema will be the greater value of this keyword in both schemas.

The resulting value of exclusiveMinimum will be the value of this keyword in whichever schema has the greater value. If both schemas to be merged have the same value for minimum, then the resulting value will be true if either of the schemas has true as the value for this keyword.

Example

schema1:

{
    "minimum": 1.31,
    "exclusiveMinimum": true
}

schema2:

{
    "minimum": 2
}

Result:

{
    "minimum": 2
}

schema1:

{
    "minimum": 2,
    "exclusiveMinimum": true
}

schema2:

{
    "minimum": 2
}

Result:

{
    "minimum": 2,
    "exclusiveMinimum": true
}

maximum and exclusiveMaximum

Rule

The resulting value of the maximum keyword in the merged schema will be the lower value of this keyword in both schemas.

The resulting value of exclusiveMaximum will be the value of this keyword in whichever schema has the lower value. If both schemas to be merged have the same value for maximum, then the resulting value will be true if either of the schemas has true as the value for this keyword.

Example

schema1:

{
    "maximum": 3,
    "exclusiveMaximum": true
}

schema2:

{
    "maximum": 2
}

Result:

{
    "maximum": 2
}

schema1:

{
    "maximum": 2,
    "exclusiveMaximum": true
}

schema2:

{
    "maximum": 2
}

Result:

{
    "maximum": 2,
    "exclusiveMaximum": true
}

required

Rule

The resulting value of this keyword will be the union of the two sets of strings in each of the schema's values, with duplicates removed.

Example

schema1:

{
    "required": [ "a", "b" ]
}

schema2:

{
   "required": [ "b", "c", "d" ]
}

Result:

{
    "required": [ "a", "b", "c", "d" ]
}

uniqueItems

Rule

The value of the keyword in the merged schema is true if and only if one of schema1 or schema2 has true as a value.

enum

Rule

The value of the keyword in the merged schema is the union of all elements in this keyword's value in both schemas, with all duplicates removed.

Example

schema1:

{
    "enum": [ 1, 2, 3, null, true, "hello" ]
}

schema2:

{
    "enum": [ 1, "world", null, false ]
}

Result:

{
    "enum": [ 1, 2, 3, null, true, false, "hello", "world" ]
}

additionalItems

Rule

The resulting value of the merged keyword will be, in order of preference:

• false;
• a schema;
• true.

If both values of this keyword in schema1 and schema2 are schemas, then the result is a merged schema as resulting from a normal schema merging.

Example

schema1:

{
    "additionalItems": { "minimum": 3 }
}

schema2:

{
    "additionalItems": true
}

Result:

{
   "additionalItems": { "minimum": 3 }
}

schema1:

{
    "additionalItems": { "minimum": 3 }
}

schema2:

{
    "additionalItems": false
}

Result:

{
   "additionalItems": false
}

items

Rule

If the value of this keyword in both schemas is a schema, then the resulting value is a merged schema as resulting from a normal schema merging.

If the value of this keyword in both schemas is an array, then the result is also a schema array with a length equal to the maximum length of both arrays, and for any given array index:

• if both schemas have a schema at the given index, the result for the index in the resulting schema is the merge of both schemas at this index;
• otherwise, the resulting schema is the one at the index for the only schema having a value.

It is an error to merge two values of items if one value is a schema and another value is a schema array.