@fastify/merge-json-schemas

What is @fastify/merge-json-schemas?

@fastify/merge-json-schemas is an npm package designed to merge multiple JSON schemas into a single schema. This is particularly useful in Fastify applications where you might have multiple schemas for different parts of your application and you want to combine them for validation or other purposes.

What are @fastify/merge-json-schemas's main functionalities?

Basic Schema Merging

This feature allows you to merge two or more JSON schemas into a single schema. The resulting schema will include all properties from the input schemas.

{"const merge = require('@fastify/merge-json-schemas');":"","const schema1 = {":"","  type: 'object',":"","  properties: {":"","    name: { type: 'string' }":"","  }":"","};":"","const schema2 = {":"","    age: { type: 'number' }":"","const mergedSchema = merge([schema1, schema2]);":"","console.log(mergedSchema);":""}

Nested Schema Merging

This feature allows you to merge nested JSON schemas. The resulting schema will include nested properties from all input schemas.

{"const merge = require('@fastify/merge-json-schemas');":"","const schema1 = {":"","  type: 'object',":"","  properties: {":"","    address: {":"","      type: 'object',":"","      properties: {":"","        street: { type: 'string' }":"","      }":"","    }":"","  }":"","};":"","const schema2 = {":"","        city: { type: 'string' }":"","const mergedSchema = merge([schema1, schema2]);":"","console.log(mergedSchema);":""}

Other packages similar to @fastify/merge-json-schemas

json-schema-merge-allof

json-schema-merge-allof is a package that merges JSON schemas using the 'allOf' keyword. It is useful for combining schemas that use the 'allOf' keyword to represent a combination of multiple schemas. Compared to @fastify/merge-json-schemas, it focuses more on the 'allOf' keyword and may not be as flexible for other types of schema merging.

json-schema-ref-parser

json-schema-ref-parser is a powerful tool for dereferencing and bundling JSON schemas. It can resolve $ref pointers in your schemas and combine them into a single schema. While it offers more advanced features like dereferencing, it may be more complex to use for simple schema merging compared to @fastify/merge-json-schemas.

deepmerge

deepmerge is a general-purpose library for deep merging of JavaScript objects. It can be used to merge JSON schemas, but it is not specifically designed for this purpose. Compared to @fastify/merge-json-schemas, deepmerge is more versatile but may require additional handling to properly merge JSON schemas.

README

@fastify/merge-json-schemas

merge-json-schemas is a JavaScript library that builds a logical product (AND) for multiple JSON schemas.

• Installation
• Usage
• API
  • mergeSchemas(schemas, options)
  • resolvers
  • defaultResolver
• License

Installation

npm i @fastify/merge-json-schemas

Usage

const assert = require('node:assert')
const { mergeSchemas } = require('@fastify/merge-json-schemas');

const schema1 = {
  $id: 'schema1',
  type: 'object',
  properties: {
    foo: { type: 'string', enum: ['foo1', 'foo2'] },
    bar: { type: 'string', minLength: 3 }
  }
}

const schema2 = {
  $id: 'schema1',
  type: 'object',
  properties: {
    foo: { type: 'string', enum: ['foo1', 'foo3'] },
    bar: { type: 'string', minLength: 5 }
  },
  required: ['foo']
}

const mergedSchema = mergeSchemas([schema1, schema2])
assert.deepStrictEqual(mergedSchema, {
  $id: 'schema1',
  type: 'object',
  properties: {
    foo: { type: 'string', enum: ['foo1'] },
    bar: { type: 'string', minLength: 5 }
  },
  required: ['foo']
})

API

mergeSchemas(schemas, options)

Builds a logical conjunction (AND) of multiple JSON schemas.

• schemas <objects[]> - list of JSON schemas to merge
• options <object> - optional options
  • resolvers <object> - custom resolvers for JSON schema keywords. Each key is the name of a JSON schema keyword. Each value is a resolver function. See keywordResolver
  • defaultResolver <function> - custom default resolver for JSON schema keywords. See keywordResolver
  • onConflict <string> - action to take when a conflict is found. Used by the default defaultResolver. Default is throw. Possible values are:
    • throw - throws an error multiple different schemas for the same keyword are found
    • ignore - do nothing if multiple different schemas for the same keyword are found
    • first - use the value of the first schema if multiple different schemas for the same keyword are found

resolvers

A list of default resolvers that merge-json-schema uses to merge JSON schemas. You can override the default resolvers by passing a list of custom resolvers in the options argument of mergeSchemas. See keywordResolver.

defaultResolver

A default resolver that merge-json-schema uses to merge JSON schemas. Default resolver is used when no custom resolver is defined for a JSON schema keyword. By default, the default resolver works as follows:

• If only one schema contains the keyword, the value of the keyword is used as the merged value
• If multiple schemas contain the exact same value for the keyword, the value of the keyword is used as the merged value
• If multiple schemas contain different values for the keyword, it throws an error

keywordResolver (keyword, values, mergedSchema, parentSchemas, options)

merge-json-schema uses a set of resolvers to merge JSON schemas. Each resolver is associated with a JSON schema keyword. The resolver is called when the keyword is found in the schemas to merge. The resolver is called with the following arguments:

• keyword <string> - the name of the keyword to merge
• values <any[]> - the values of the keyword to merge. The length of the array is equal to the number of schemas to merge. If a schema does not contain the keyword, the value is undefined
• mergedSchema <object> - an instance of the merged schema
• parentSchemas <object[]> - the list of parent schemas
• options <object> - the options passed to mergeSchemas

The resolver must set the merged value of the keyword in the mergedSchema object.

Example: resolver for the minNumber keyword.

function minNumberResolver (keyword, values, mergedSchema) {
  mergedSchema[keyword] = Math.min(...values)
}

License

Licensed under MIT.