json-schema-merge-allof

What is json-schema-merge-allof?

The json-schema-merge-allof npm package is designed to merge multiple JSON Schemas that use the 'allOf' keyword into a single schema. This can be particularly useful when dealing with complex schemas that need to be simplified or when combining schemas from different sources.

What are json-schema-merge-allof's main functionalities?

Merge Multiple Schemas

This feature allows you to merge multiple JSON Schemas into a single schema. The code sample demonstrates merging two schemas, one with a 'name' property and another with an 'age' property, into a single schema.

const mergeAllOf = require('json-schema-merge-allof');

const schema1 = {
  type: 'object',
  properties: {
    name: { type: 'string' }
  }
};

const schema2 = {
  type: 'object',
  properties: {
    age: { type: 'integer' }
  }
};

const mergedSchema = mergeAllOf({ allOf: [schema1, schema2] });
console.log(JSON.stringify(mergedSchema, null, 2));

Handle Conflicting Schemas

This feature demonstrates how the package handles conflicting schemas. In this example, both schemas have a 'name' property but with different types. The package will throw an error indicating the conflict.

const mergeAllOf = require('json-schema-merge-allof');

const schema1 = {
  type: 'object',
  properties: {
    name: { type: 'string' }
  }
};

const schema2 = {
  type: 'object',
  properties: {
    name: { type: 'integer' }
  }
};

try {
  const mergedSchema = mergeAllOf({ allOf: [schema1, schema2] });
  console.log(JSON.stringify(mergedSchema, null, 2));
} catch (error) {
  console.error('Error merging schemas:', error.message);
}

Other packages similar to json-schema-merge-allof

json-schema-deref

The json-schema-deref package is used to dereference JSON Schema $ref pointers, resolving them to their full definitions. Unlike json-schema-merge-allof, which focuses on merging schemas, json-schema-deref is more about resolving references within a schema.

json-schema-ref-parser

The json-schema-ref-parser package is a powerful tool for parsing, resolving, and dereferencing JSON Schema $ref pointers. It offers more advanced features for handling complex schemas with references, whereas json-schema-merge-allof is specifically designed for merging schemas using the 'allOf' keyword.

ajv

Ajv is a JSON Schema validator that supports JSON Schema draft-07 and later. While it includes some features for schema merging, its primary focus is on validation. It is more comprehensive in terms of validation capabilities compared to json-schema-merge-allof, which is specialized for merging schemas.

README

json-schema-merge-allof

Merge schemas combined using allOf into a more readable composed schema free from allOf.

npm install json-schema-compare --save

Features

• Real and safe merging of schemas combined with allOf
• Results in a more readable root schema
• Removes almost all logical impossibilities
• Throws if no logical intersection is found (your schema would not validate anything from the start)
• Validates in a way not possible by regular simple meta validators
• Pluggable keyword resolvers
• Option to override common impossibility like adding properties when using additionalProperties: false
• Supports all json schema keywords

How

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:

• minLength, minimum, minItems etc chooses the highest value of the conflicting values.
• maxLength, maximum, maxItems etc chooses the lowest value of the conflicting values.
• uniqueItems is true if any of the conflicting values are true

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:

pattern

If a schema have the pattern keyword and we have a conflict, then we need to leave that expressed like this:

{
  type: 'string',
  allOf: [{
    pattern: '\\w+\\s\\w+'
  }, {
    pattern: '123$'
  }]
}

Regular expressions does not have an AND operator, only OR.

not

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.

Options

resolvers Object Override any default resolver like this:

mergeAllOf(schema, {
  resolvers: {
    title: function(values, key, mergeSchemas) {
      // 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:

• values: an array of the conflicting values that need to be resolved
• key the name of the keyword that caused the resolver to be called (useful if you use the same resolver for multiple keywords)
• mergeSchemas a function you can call that merges an array of schemas

ignoreAdditionalProperties default false

Allows you to combine schema properties even though some schemas have additionalProperties: false The resulting schema will still get additionalProperties set to false. This is the most common issue people face when trying to expand schemas using allOf and a limitation of the json schema spec.

Resolvers

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.

Lossy vs lossless

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.

$ref

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 are not the task of this library.

Other libraries

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.

Restrictions

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.

Roadmap

• Treat the interdependent validations like properties and additionalProperties as one resolver
• Implement a proper compare function that ignores sort on required, type, etc. And possibly title, description, etc.
• Extract repeating validators from anyOf/oneOf and merge them with parent schema
• After extraction of validators from anyOf/oneOf, compare them and remove duplicates.
• If left with only one in anyOf/oneOf then merge it to the parent schema.
• Expose seperate tools for validation, extraction
• Consider adding even more logical validation (like minLength <= maxLength)

Contributing

Create tests for new functionality and follow the eslint rules.

License

MIT © Martin Hansen