JSON schema file combination

Combination overview

The combination process for JSON Schema files and the target use cases for it are similar to the process and use cases for Swagger schemas.

JSON schema combination specifics

Most of the differences between JSON Schema combination and Swagger schema combination involve two sets of specific details. These details include which elements are combined through which mechanism as well as how combinations are validated. Details about how you combine each element are listed in JSON schema file specification. The documentation does not cover explicitly how to validate combinations. However, validating the combination of JSON schemas follows the same philosophy as for validating the combination of Swagger schemas. Moreover, if A combines with B, the resulting document A' is a logical extension or superset of B. In addition, A' does not contain any destructive changes such as changes to the type of a property.

Structural comparisons

The primary characteristic that is unique to JSON Schema is how references are compared across versions. For example, suppose we have the schema Base:

"Foo" : {
  "properties" : {
    "bar" : { "$ref" : "#/definitions/Bar" }
  }
},
"Bar" : {
  "properties" : {
    "name" : { "type" : "string" }
  }
}

Suppose also that the schema Ext combines the schema Base. In addition, suppose that the schema Ext redefines the bar property to point to the Baz definition instead:

"Foo" : {
  "properties" : {
    "bar" : { "$ref" : "#/definitions/Baz" }
  }
},
"Baz" : {
  "properties" : {
    "name" : { "type" : "string" },
    "value" : { "type" : "string" }
  }
}

The validation algorithm for JSON schema combination declares this to be a legal change. The reason for allowing the change is because the validation algorithm compares the type references structurally rather than nominally. The distinction is that while deciding if two referenced types are compatible, the comparison algorithm ignores the names given to the schema definitions. Instead, the algorithm examines the structure that the definitions set forth.

In this case, the algorithm compares the Baz definition with the Bar definition. The algorithm determines whether Baz is a logical superset of Bar. Baz contains all the properties of Bar, and these properties have the same types. As such, the algorithm finds that substituting Baz in place of Bar is legal.

This structural comparison algorithm processes object and array object references recursively. Moreover, suppose that Baz and Bar both had properties that mapped to other objects or arrays of objects. In this case, the algorithm would compare each of these references structurally until the algorithm reaches the end of the tree.

The rough net effect of the structural comparison algorithm is to allow reference changes. This allowance is inclusive of reference changes that are inherent given import overrides. The net effect of this rule is that any data that validates at runtime against the old schema definition also validates against the new schema definition.