Merge schemas combined using allOf into a more readable composed schema free from allOf.
npm install json-schema-merge-allof --save
Since allOf require ALL schemas provided (including the parent schema) to apply, we can iterate over all the schemas, extracting all the values for say, type, and find the intersection of valid values. Here is an example:
{
type: ['object', 'null'],
additionalProperties: {
type: 'string',
minLength: 5
},
allOf: [{
type: ['array', 'object'],
additionalProperties: {
type: 'string',
minLength: 10,
maxLength: 20
}
}]
}
This result in the schema :
{
type: 'object',
additionalProperties: {
type: 'string',
minLength: 10,
maxLength: 20
}
}
Notice that type now excludes null and array since those are not logically possible. Also minLength is raised to 10. The other properties have no conflict and are merged into the root schema with no resolving needed.
For other keywords other methods are used, here are some simple examples:
As you can see above the strategy is to choose the most restrictive of the set of values that conflict. For some keywords that is done by intersection, for others like required it is done by a union of all the values, since that is the most restrictive.
What you are left with is a schema completely free of allOf. Except for in a couple of values that are impossible to properly intersect/combine:
When multiple conflicting not values are found, we also use the approach that pattern use, but instead of allOf we use anyOf. When extraction of common rules from anyOf is in place this can be further simplified.
ignoreAdditionalProperties default false
Allows you to combine schema properties even though some schemas have additionalProperties: false
This is the most common issue people face when trying to expand schemas using allOf and a limitation of the json schema spec. Be aware though that the schema produced will allow more than the original schema. But this is useful if just want to combine schemas using allOf as if additionalProperties wasn't false during the merge process. The resulting schema will still get additionalProperties set to false.
deep boolean, default true
If false, resolves only the top-level allOf
keyword in the schema.
If true, resolves all allOf
keywords in the schema.
resolvers Object Override any default resolver like this:
mergeAllOf(schema, {
resolvers: {
title: function(values, path, mergeSchemas, options) {
// choose what title you want to be used based on the conflicting values
// resolvers MUST return a value other than undefined
}
}
})
The function is passed:
Some keyword are dependant on other keywords, like properties, patternProperties, additionalProperties. To create a resolver for these the resolver requires this structure:
mergeAllOf(schema, {
resolvers: {
properties:
keywords: ['properties', 'patternProperties', 'additionalProperties'],
resolver(values, parents, mergers, options) {
}
}
}
})
This type of resolvers are expected to return an object containing the resolved values of all the associated keywords. The keys must be the name of the keywords. So the properties resolver need to return an object like this containing the resolved values for each keyword:
{
properties: ...,
patternProperties: ...,
additionalProperties: ...,
}
Also the resolve function is not passed mergeSchemas, but an object mergers that contains mergers for each of the related keywords. So properties get passed an object like this:
const mergers = {
properties: function mergeSchemas(schemas, childSchemaName){...},
patternProperties: function mergeSchemas(schemas, childSchemaName){...},
additionalProperties: function mergeSchemas(schemas){...},
}
Some of the mergers requires you to supply a string of the name or index of the subschema you are currently merging. This is to make sure the path passed to child resolvers are correct.
You can set a default resolver that catches any unknown keyword. Let's say you want to use the same strategy as the ones for the meta keywords, to use the first value found. You can accomplish that like this:
mergeJsonSchema({
...
}, {
resolvers: {
defaultResolver: mergeJsonSchema.options.resolvers.title
}
})
Resolvers are called whenever multiple conflicting values are found on the same position in the schemas.
You can override a resolver by supplying it in the options.
All built in reducers for validation keywords are lossless, meaning that they don't remove or add anything in terms of validation.
For meta keywords like title, description, $id, $schema, default the strategy is to use the first possible value if there are conflicting ones. So the root schema is prioritized. This process possibly removes some meta information from your schema. So it's lossy. Override this by providing custom resolvers.
If one of your schemas contain a $ref property you should resolve them using a ref resolver like json-schema-ref-parser to dereference your schema for you first. Resolving $refs is not the task of this library. Currently it does not support circular references either. But if you use bundle
in json-schema-ref-parser it should work as expected.
There exists some libraries that claim to merge schemas combined with allOf, but they just merge schemas using a very basic logic. Basically just the same as lodash merge. So you risk ending up with a schema that allows more or less than the original schema would allow.
We cannot merge schemas that are a logical impossibility, like:
{
type: 'object',
allOf: [{
type: 'array'
}]
}
The library will then throw an error reporting the values that had no valid intersection. But then again, your original schema wouldn't validate anything either.
Create tests for new functionality and follow the eslint rules.
MIT © Martin Hansen