{"id":15233447,"url":"https://github.com/stoplightio/json-schema-merge-allof","last_synced_at":"2025-10-04T18:31:43.963Z","repository":{"id":45871563,"uuid":"192035094","full_name":"stoplightio/json-schema-merge-allof","owner":"stoplightio","description":"Simplify your schema by combining allOf","archived":false,"fork":true,"pushed_at":"2025-01-16T05:13:28.000Z","size":418,"stargazers_count":0,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-18T22:42:50.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mokkabonna/json-schema-merge-allof","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stoplightio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-15T04:08:09.000Z","updated_at":"2024-01-02T08:42:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stoplightio/json-schema-merge-allof","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fjson-schema-merge-allof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fjson-schema-merge-allof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fjson-schema-merge-allof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stoplightio%2Fjson-schema-merge-allof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stoplightio","download_url":"https://codeload.github.com/stoplightio/json-schema-merge-allof/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235289305,"owners_count":18965918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-29T05:08:57.223Z","updated_at":"2025-10-04T18:31:38.609Z","avatar_url":"https://github.com/stoplightio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# json-schema-merge-allof\n\n\u003e Merge schemas combined using allOf into a more readable composed schema free from allOf.\n\n```bash\nnpm install json-schema-merge-allof --save\n```\n\n## Features\n\n- **Real** and **safe** merging of schemas combined with **allOf**\n- Takes away all allOf found in the whole schema\n- Lossless in terms of validation rules, merged schema does not validate more or less than the original schema\n- Results in a more readable root schema\n- Removes almost all logical impossibilities\n- Throws if no logical intersection is found (your schema would not validate anything from the start)\n- Validates in a way not possible by regular simple meta validators\n- Correctly considers additionalProperties, patternProperties and properties as a part of an whole when merging schemas containing those\n- Correctly considers items and additionalItems as a whole when merging schemas containing those\n- Supports merging schemas with items as array and direct schema\n- Supports merging dependencies when mixed array and schema\n- Supports all JSON schema core/validation keywords (v6, use custom resolvers to support other keywords)\n- Option to override common impossibility like adding properties when using **additionalProperties: false**\n- Pluggable keyword resolvers\n\n## How\n\nSince 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:\n\n```js\n{\n  type: ['object', 'null'],\n  additionalProperties: {\n    type: 'string',\n    minLength: 5\n  },\n  allOf: [{\n    type: ['array', 'object'],\n    additionalProperties: {\n      type: 'string',\n      minLength: 10,\n      maxLength: 20\n    }\n  }]\n}\n```\n\nThis result in the schema :\n```js\n{\n  type: 'object',\n  additionalProperties: {\n    type: 'string',\n    minLength: 10,\n    maxLength: 20\n  }\n}\n```\n\nNotice 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.\n\nFor other keywords other methods are used, here are some simple examples:\n\n- minLength, minimum, minItems etc chooses the **highest** value of the conflicting values.\n- maxLength, maximum, maxItems etc chooses the **lowest** value of the conflicting values.\n- uniqueItems is true if **any** of the conflicting values are true\n\nAs 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.\n\nWhat 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:\n\n### not\n\nWhen 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.\n\n## Options\n**ignoreAdditionalProperties** default **false**\n\nAllows 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.\n\n**resolvers** Object\nOverride any default resolver like this:\n\n```js\nmergeAllOf(schema, {\n  resolvers: {\n    title: function(values, path, mergeSchemas, options) {\n      // choose what title you want to be used based on the conflicting values\n      // resolvers MUST return a value other than undefined\n    }\n  }\n})\n```\n\n**deep** boolean, default *true*\nIf false, resolves only the top-level `allOf` keyword in the schema.\n\nIf true, resolves all `allOf` keywords in the schema.\n\nThe function is passed:\n\n- **values** an array of the conflicting values that need to be resolved\n- **path** an array of strings containing the path to the position in the schema that caused the resolver to be called (useful if you use the same resolver for multiple keywords, or want to implement specific logic for custom paths)\n- **mergeSchemas** a function you can call that merges an array of schemas\n- **options** the options mergeAllOf was called with\n\n\n### Combined resolvers\nNo separate resolver is called for patternProperties and additionalProperties, only the properties resolver is called. Same for additionalItems, only items resolver is called. This is because those keywords need to be resolved together as they affect each other.\n\nThose two 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:\n\n```js\n{\n    properties: ...,\n    patternProperties: ...,\n    additionalProperties: ...,\n}\n```\n\nAlso 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:\n\n```js\nvar mergers = {\n    properties: function mergeSchemas(schemas, childSchemaName){...},\n    patternProperties: function mergeSchemas(schemas, childSchemaName){...},\n    additionalProperties: function mergeSchemas(schemas){...},\n}\n```\n\nSome 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.\n\n### Default resolver\nYou 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:\n\n```js\nmergeJsonSchema({\n  ...\n}, {\n  resolvers: {\n    defaultResolver: mergeJsonSchema.options.resolvers.title\n  }\n})\n```\n\n\n## Resolvers\n\nResolvers are called whenever multiple conflicting values are found on the same position in the schemas.\n\nYou can override a resolver by supplying it in the options.\n\n### Lossy vs lossless\n\nAll built in reducers for validation keywords are lossless, meaning that they don't remove or add anything in terms of validation.\n\nFor 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.\n\n\n## $ref\n\nIf one of your schemas contain a $ref property you should resolve them using a ref resolver like [json-schema-ref-parser](https://github.com/BigstickCarpet/json-schema-ref-parser) to dereference your schema for you first. Resolving $refs is not the task of this library.\n\n\n## Other libraries\n\nThere 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.\n\n\n## Restrictions\n\nWe cannot merge schemas that are a logical impossibility, like:\n\n```js\n{\n  type: 'object',\n  allOf: [{\n    type: 'array'\n  }]\n}\n```\n\nThe 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.\n\n\n## Roadmap\n\n- [x] Treat the interdependent validations like properties and additionalProperties as one resolver (and items additionalItems)\n- [ ] Extract repeating validators from anyOf/oneOf and merge them with parent schema\n- [ ] After extraction of validators from anyOf/oneOf, compare them and remove duplicates.\n- [ ] If left with only one in anyOf/oneOf then merge it to the parent schema.\n- [ ] Expose seperate tools for validation, extraction\n- [ ] Consider adding even more logical validation (like minLength \u003c= maxLength)\n\n## Contributing\n\nCreate tests for new functionality and follow the eslint rules.\n\n### Release to NPM\n\nTo create a release:\n-  Ensure all changes for the release are merged into the `master` branch. \n- Update your local `master` branch with upstream\n- Run `git tag \u003c*.*.*\u003e` to tag a new version, following semver guidelines for bumping the version. For example: `git tag 0.7.6`\n- Run `git push origin \u003c*.*.*\u003e`\n\nAfter you push the tag, the circleci workflow will publish to npm. \n\n## License\n\nMIT © [Martin Hansen](http://martinhansen.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoplightio%2Fjson-schema-merge-allof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstoplightio%2Fjson-schema-merge-allof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstoplightio%2Fjson-schema-merge-allof/lists"}