{ "$schema": "http://json-schema.org/draft-07/schema#", "additionalProperties": false, "definitions": { "ConfigurationInfoOverride": { "$ref": "#/definitions/ConfigurationInfoOverride_1", "description": "The subset of `info` worth overriding from a configuration file.\n\nDeliberately not the full Info object: `version` and `title` are the ones\npeople ask for, and description rounds it out. Kept narrow so the generated\nschema stays readable and `--noExtraProps` still catches typos.", "title": "ConfigurationInfoOverride" }, "ConfigurationInfoOverride_1": { "$ref": "#/definitions/__type_5" }, "ConfigurationInput": { "anyOf": [ { "additionalProperties": false, "properties": { "description": { "$ref": "#/definitions/DescriptionMergeBehaviour", "description": "This configuration setting lets you configure how the info.description from this OpenAPI file will be merged\ninto the final resulting OpenAPI file", "examples": [ { "append": true }, { "append": true, "title": { "value": "Title 1" } }, { "append": true, "title": { "headingLevel": 2, "value": "Title Level 2" } }, { "append": true, "title": { "headingLevel": 6, "value": "Inperceptible title" } } ], "title": "description" }, "disputePrefix": { "description": "The prefix that will be used in the event of a conflict of two definition names.", "minLength": 1, "title": "disputePrefix", "type": "string" }, "duplicatePathHandling": { "description": "What to do when this input declares a path (or webhook) that an earlier\ninput already contributed (issue #71).\n\n- `error` (default) — fail the merge, as it always has.\n- `skip-later` — keep the definition already present, drop this one.\n- `prefer-later` — replace the definition already present with this one.\n- `merge-operations` — combine them when their methods do not overlap and\n their path-level fields agree, so `GET /thing` from one input and\n `POST /thing` from another end up in one path item. Refuses rather than\n guessing when the methods overlap, the path-level fields differ, or\n either side is a `$ref`.\n\nPer input rather than global, so a configuration can say \"this gateway\ninput wins and the rest are additive\".", "enum": [ "error", "merge-operations", "prefer-later", "skip-later" ], "title": "duplicatePathHandling", "type": "string" }, "inputFile": { "description": "The path to the input OpenAPI Schema that will be merged.", "minLength": 1, "title": "inputFile", "type": "string" }, "operationSelection": { "$ref": "#/definitions/OperationSelection", "description": "Choose which OpenAPI Operations should be included from this input.", "examples": [ { "includeTags": [ "include-this-tag-only" ] }, { "excludeTags": [ "exclude-these-tags" ] }, { "excludeTags": [ "filter-out-with-this-tag" ], "includeTags": [ "select-this-first" ] }, { "includePaths": [ { "path": "/admin/*" } ] }, { "excludePaths": [ { "method": "get", "path": "/admin/users" } ] } ], "title": "operationSelection" }, "pathModification": { "$ref": "#/definitions/PathModification", "description": "For this input, you can perform these modifications to its paths elements.", "examples": [ { "stripStart": "Model" }, { "prepend": "Model" }, { "prepend": "Object", "stripStart": "Jira" } ], "title": "pathModification" }, "tag": { "$ref": "#/definitions/TagInjectionConfig", "description": "Add a tag to every operation from this input (issue #112).\n\nLets the merged document say which service an operation came from without\nediting the upstream specification. Applied after `operationSelection`, so\nthe injected tag cannot influence which operations survive.", "examples": [ { "name": "billing" }, { "description": "Everything served by the billing service.", "name": "billing" } ], "title": "tag" } }, "required": [ "inputFile" ], "type": "object" }, { "additionalProperties": false, "properties": { "description": { "$ref": "#/definitions/DescriptionMergeBehaviour", "description": "This configuration setting lets you configure how the info.description from this OpenAPI file will be merged\ninto the final resulting OpenAPI file", "examples": [ { "append": true }, { "append": true, "title": { "value": "Title 1" } }, { "append": true, "title": { "headingLevel": 2, "value": "Title Level 2" } }, { "append": true, "title": { "headingLevel": 6, "value": "Inperceptible title" } } ], "title": "description" }, "disputePrefix": { "description": "The prefix that will be used in the event of a conflict of two definition names.", "minLength": 1, "title": "disputePrefix", "type": "string" }, "duplicatePathHandling": { "description": "What to do when this input declares a path (or webhook) that an earlier\ninput already contributed (issue #71).\n\n- `error` (default) — fail the merge, as it always has.\n- `skip-later` — keep the definition already present, drop this one.\n- `prefer-later` — replace the definition already present with this one.\n- `merge-operations` — combine them when their methods do not overlap and\n their path-level fields agree, so `GET /thing` from one input and\n `POST /thing` from another end up in one path item. Refuses rather than\n guessing when the methods overlap, the path-level fields differ, or\n either side is a `$ref`.\n\nPer input rather than global, so a configuration can say \"this gateway\ninput wins and the rest are additive\".", "enum": [ "error", "merge-operations", "prefer-later", "skip-later" ], "title": "duplicatePathHandling", "type": "string" }, "inputURL": { "description": "The input url that we should load our configuration file from.", "format": "uri", "pattern": "^https?://", "title": "inputURL", "type": "string" }, "operationSelection": { "$ref": "#/definitions/OperationSelection", "description": "Choose which OpenAPI Operations should be included from this input.", "examples": [ { "includeTags": [ "include-this-tag-only" ] }, { "excludeTags": [ "exclude-these-tags" ] }, { "excludeTags": [ "filter-out-with-this-tag" ], "includeTags": [ "select-this-first" ] }, { "includePaths": [ { "path": "/admin/*" } ] }, { "excludePaths": [ { "method": "get", "path": "/admin/users" } ] } ], "title": "operationSelection" }, "pathModification": { "$ref": "#/definitions/PathModification", "description": "For this input, you can perform these modifications to its paths elements.", "examples": [ { "stripStart": "Model" }, { "prepend": "Model" }, { "prepend": "Object", "stripStart": "Jira" } ], "title": "pathModification" }, "tag": { "$ref": "#/definitions/TagInjectionConfig", "description": "Add a tag to every operation from this input (issue #112).\n\nLets the merged document say which service an operation came from without\nediting the upstream specification. Applied after `operationSelection`, so\nthe injected tag cannot influence which operations survive.", "examples": [ { "name": "billing" }, { "description": "Everything served by the billing service.", "name": "billing" } ], "title": "tag" } }, "required": [ "inputURL" ], "type": "object" }, { "additionalProperties": false, "properties": { "description": { "$ref": "#/definitions/DescriptionMergeBehaviour", "description": "This configuration setting lets you configure how the info.description from this OpenAPI file will be merged\ninto the final resulting OpenAPI file", "examples": [ { "append": true }, { "append": true, "title": { "value": "Title 1" } }, { "append": true, "title": { "headingLevel": 2, "value": "Title Level 2" } }, { "append": true, "title": { "headingLevel": 6, "value": "Inperceptible title" } } ], "title": "description" }, "dispute": { "$ref": "#/definitions/Dispute", "description": "The dispute algorithm that should be used for this input.", "examples": [ { "prefix": "SomePrefix" }, { "alwaysApply": true, "prefix": "SomePrefix" }, { "suffix": "Some suffix" }, { "alwaysApply": true, "suffix": "Some suffix" } ], "title": "dispute" }, "duplicatePathHandling": { "description": "What to do when this input declares a path (or webhook) that an earlier\ninput already contributed (issue #71).\n\n- `error` (default) — fail the merge, as it always has.\n- `skip-later` — keep the definition already present, drop this one.\n- `prefer-later` — replace the definition already present with this one.\n- `merge-operations` — combine them when their methods do not overlap and\n their path-level fields agree, so `GET /thing` from one input and\n `POST /thing` from another end up in one path item. Refuses rather than\n guessing when the methods overlap, the path-level fields differ, or\n either side is a `$ref`.\n\nPer input rather than global, so a configuration can say \"this gateway\ninput wins and the rest are additive\".", "enum": [ "error", "merge-operations", "prefer-later", "skip-later" ], "title": "duplicatePathHandling", "type": "string" }, "inputFile": { "description": "The path to the input OpenAPI Schema that will be merged.", "minLength": 1, "title": "inputFile", "type": "string" }, "operationSelection": { "$ref": "#/definitions/OperationSelection", "description": "Choose which OpenAPI Operations should be included from this input.", "examples": [ { "includeTags": [ "include-this-tag-only" ] }, { "excludeTags": [ "exclude-these-tags" ] }, { "excludeTags": [ "filter-out-with-this-tag" ], "includeTags": [ "select-this-first" ] }, { "includePaths": [ { "path": "/admin/*" } ] }, { "excludePaths": [ { "method": "get", "path": "/admin/users" } ] } ], "title": "operationSelection" }, "pathModification": { "$ref": "#/definitions/PathModification", "description": "For this input, you can perform these modifications to its paths elements.", "examples": [ { "stripStart": "Model" }, { "prepend": "Model" }, { "prepend": "Object", "stripStart": "Jira" } ], "title": "pathModification" }, "tag": { "$ref": "#/definitions/TagInjectionConfig", "description": "Add a tag to every operation from this input (issue #112).\n\nLets the merged document say which service an operation came from without\nediting the upstream specification. Applied after `operationSelection`, so\nthe injected tag cannot influence which operations survive.", "examples": [ { "name": "billing" }, { "description": "Everything served by the billing service.", "name": "billing" } ], "title": "tag" } }, "required": [ "inputFile" ], "type": "object" }, { "additionalProperties": false, "properties": { "description": { "$ref": "#/definitions/DescriptionMergeBehaviour", "description": "This configuration setting lets you configure how the info.description from this OpenAPI file will be merged\ninto the final resulting OpenAPI file", "examples": [ { "append": true }, { "append": true, "title": { "value": "Title 1" } }, { "append": true, "title": { "headingLevel": 2, "value": "Title Level 2" } }, { "append": true, "title": { "headingLevel": 6, "value": "Inperceptible title" } } ], "title": "description" }, "dispute": { "$ref": "#/definitions/Dispute", "description": "The dispute algorithm that should be used for this input.", "examples": [ { "prefix": "SomePrefix" }, { "alwaysApply": true, "prefix": "SomePrefix" }, { "suffix": "Some suffix" }, { "alwaysApply": true, "suffix": "Some suffix" } ], "title": "dispute" }, "duplicatePathHandling": { "description": "What to do when this input declares a path (or webhook) that an earlier\ninput already contributed (issue #71).\n\n- `error` (default) — fail the merge, as it always has.\n- `skip-later` — keep the definition already present, drop this one.\n- `prefer-later` — replace the definition already present with this one.\n- `merge-operations` — combine them when their methods do not overlap and\n their path-level fields agree, so `GET /thing` from one input and\n `POST /thing` from another end up in one path item. Refuses rather than\n guessing when the methods overlap, the path-level fields differ, or\n either side is a `$ref`.\n\nPer input rather than global, so a configuration can say \"this gateway\ninput wins and the rest are additive\".", "enum": [ "error", "merge-operations", "prefer-later", "skip-later" ], "title": "duplicatePathHandling", "type": "string" }, "inputURL": { "description": "The input url that we should load our configuration file from.", "format": "uri", "pattern": "^https?://", "title": "inputURL", "type": "string" }, "operationSelection": { "$ref": "#/definitions/OperationSelection", "description": "Choose which OpenAPI Operations should be included from this input.", "examples": [ { "includeTags": [ "include-this-tag-only" ] }, { "excludeTags": [ "exclude-these-tags" ] }, { "excludeTags": [ "filter-out-with-this-tag" ], "includeTags": [ "select-this-first" ] }, { "includePaths": [ { "path": "/admin/*" } ] }, { "excludePaths": [ { "method": "get", "path": "/admin/users" } ] } ], "title": "operationSelection" }, "pathModification": { "$ref": "#/definitions/PathModification", "description": "For this input, you can perform these modifications to its paths elements.", "examples": [ { "stripStart": "Model" }, { "prepend": "Model" }, { "prepend": "Object", "stripStart": "Jira" } ], "title": "pathModification" }, "tag": { "$ref": "#/definitions/TagInjectionConfig", "description": "Add a tag to every operation from this input (issue #112).\n\nLets the merged document say which service an operation came from without\nediting the upstream specification. Applied after `operationSelection`, so\nthe injected tag cannot influence which operations survive.", "examples": [ { "name": "billing" }, { "description": "Everything served by the billing service.", "name": "billing" } ], "title": "tag" } }, "required": [ "inputURL" ], "type": "object" } ], "description": "The multiple types of configuration inputs that are supported.", "title": "ConfigurationInput" }, "DescriptionMergeBehaviour": { "$ref": "#/definitions/DescriptionMergeBehaviour_1", "title": "DescriptionMergeBehaviour" }, "DescriptionMergeBehaviour_1": { "$ref": "#/definitions/__type_2" }, "DescriptionTitle": { "$ref": "#/definitions/DescriptionTitle_1", "title": "DescriptionTitle" }, "DescriptionTitle_1": { "$ref": "#/definitions/__type_3" }, "Dispute": { "anyOf": [ { "$ref": "#/definitions/DisputePrefix" }, { "$ref": "#/definitions/DisputeSuffix" } ], "title": "Dispute" }, "DisputePrefix": { "additionalProperties": false, "description": "A dispute with a configurable prefix.", "properties": { "alwaysApply": { "default": false, "description": "If this is set to true, then this prefix will always be applied to every Schema, even if there is no dispute\nfor that particular schema. This may prevent the deduplication of common schemas from different OpenApi files.", "title": "alwaysApply", "type": "boolean" }, "prefix": { "description": "The prefix to use when a schema is in dispute.", "minLength": 1, "title": "prefix", "type": "string" } }, "required": [ "prefix" ], "title": "DisputePrefix", "type": "object" }, "DisputeSuffix": { "additionalProperties": false, "description": "A dispute with a configurable suffix.", "properties": { "alwaysApply": { "default": false, "description": "If this is set to true, then this prefix will always be applied to every Schema, even if there is no dispute\nfor that particular schema. This may prevent the deduplication of common schemas from different OpenApi files.", "title": "alwaysApply", "type": "boolean" }, "suffix": { "description": "The suffix to use when a schema is in dispute.", "minLength": 1, "title": "suffix", "type": "string" } }, "required": [ "suffix" ], "title": "DisputeSuffix", "type": "object" }, "ExtensionMergeNode": { "anyOf": [ { "additionalProperties": false, "properties": { "kind": { "const": "scalar", "title": "kind", "type": "string" }, "strategy": { "enum": [ "error", "first", "last" ], "title": "strategy", "type": "string" } }, "required": [ "kind", "strategy" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "array", "title": "kind", "type": "string" }, "strategy": { "enum": [ "error", "first", "last" ], "title": "strategy", "type": "string" } }, "required": [ "kind", "strategy" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "array", "title": "kind", "type": "string" }, "sortBy": { "title": "sortBy", "type": "string" }, "strategy": { "enum": [ "concat", "concat-unique" ], "title": "strategy", "type": "string" } }, "required": [ "kind", "strategy" ], "type": "object" }, { "additionalProperties": false, "properties": { "item": { "$ref": "#/definitions/ExtensionMergeNode", "title": "item" }, "key": { "title": "key", "type": "string" }, "kind": { "const": "array", "title": "kind", "type": "string" }, "strategy": { "const": "union-by-key", "title": "strategy", "type": "string" } }, "required": [ "item", "key", "kind", "strategy" ], "type": "object" }, { "additionalProperties": false, "properties": { "kind": { "const": "object", "title": "kind", "type": "string" }, "strategy": { "enum": [ "error", "first", "last" ], "title": "strategy", "type": "string" } }, "required": [ "kind", "strategy" ], "type": "object" }, { "additionalProperties": false, "properties": { "fields": { "additionalProperties": { "$ref": "#/definitions/ExtensionMergeNode" }, "title": "fields", "type": "object" }, "kind": { "const": "object", "title": "kind", "type": "string" }, "strategy": { "const": "merge", "title": "strategy", "type": "string" } }, "required": [ "kind", "strategy" ], "type": "object" } ], "description": "How to combine one document-root `x-*` extension's value across inputs\n(proposal 48, generalising issue #60). Mirrors the extension value's own\nJSON shape: `kind` says what shape is expected at this point, `strategy`\nsays how to combine it.\n\n`kind` only changes behaviour for `concat`, `concat-unique`, `union-by-key`\nand `merge`, which inspect the value's internal structure and fall back to\ntaking the first input's value wholesale if it does not match. `first`,\n`last` and `error` work on a value of any shape -- `kind` on those three is\ndeclarative only, and in particular `error` still reports a disagreement\neven if the value is not the shape `kind` names, because silently doing\nnothing is the one behaviour that strategy must never have.", "title": "ExtensionMergeNode" }, "Indent": { "anyOf": [ { "$ref": "#/definitions/SpaceIndent" }, { "$ref": "#/definitions/TabIndent" } ], "description": "Discriminated union of indentation strategies. The `style` tag is the\nsingle source of truth and is exhaustively dispatched on in\n`indentToJsonStringifyArg`.", "title": "Indent" }, "OperationSelection": { "$ref": "#/definitions/OperationSelection_1", "title": "OperationSelection" }, "OperationSelection_1": { "$ref": "#/definitions/__type_1" }, "OutputFormatting": { "$ref": "#/definitions/OutputFormatting_1", "description": "Output formatting controls for the merged document.", "title": "OutputFormatting" }, "OutputFormatting_1": { "additionalProperties": false, "description": "Output formatting controls for the merged document.", "properties": { "indent": { "$ref": "#/definitions/Indent", "description": "Indentation style for the emitted output. Defaults to\n`{ style: 'spaces', width: 2 }`, which preserves the historical\nbehaviour.", "title": "indent" } }, "title": "OutputFormatting_1", "type": "object" }, "PathModification": { "$ref": "#/definitions/PathModification_1", "title": "PathModification" }, "PathModification_1": { "$ref": "#/definitions/__type" }, "SpaceIndent": { "additionalProperties": false, "description": "Use space characters for indentation, repeated `width` times per level.", "properties": { "style": { "const": "spaces", "title": "style", "type": "string" }, "width": { "$ref": "#/definitions/SpaceIndentWidth", "title": "width" } }, "required": [ "style", "width" ], "title": "SpaceIndent", "type": "object" }, "SpaceIndentWidth": { "description": "Width of one indent step when using spaces. Range chosen to cover every\nrealistic style (2, 4, 8); larger values are almost certainly a config\nerror and are rejected at validation time.", "maximum": 8, "minimum": 1, "title": "SpaceIndentWidth", "type": "integer" }, "TabIndent": { "additionalProperties": false, "description": "Use tab characters for indentation. JSON only — YAML 1.1 disallows tabs\nas indentation, so combining this with a `.yaml` / `.yml` output is\nrejected at configuration-load time with a clear error message.", "properties": { "style": { "const": "tabs", "title": "style", "type": "string" } }, "required": [ "style" ], "title": "TabIndent", "type": "object" }, "TagInjectionConfig": { "$ref": "#/definitions/TagInjectionConfig_1", "description": "A tag applied to every operation from one input.", "title": "TagInjectionConfig" }, "TagInjectionConfig_1": { "$ref": "#/definitions/__type_4" }, "__type": { "additionalProperties": false, "properties": { "prepend": { "description": "Append these characters to the start of the paths for this input. Will run after stripStart.", "minLength": 1, "title": "prepend", "type": "string" }, "stripStart": { "description": "If a path starts with these characters, then stip them from the beginning of the path. Will run before prepend.", "minLength": 1, "title": "stripStart", "type": "string" } }, "title": "__type", "type": "object" }, "__type_1": { "additionalProperties": false, "properties": { "excludePaths": { "description": "Any Operation whose path (and, if given, method) matches one of these selectors will be excluded from the\nfinal result. If an Operation is matched by both an includePaths and an excludePaths selector, or by an\nexclude rule of either kind (path or tag), exclusion takes precedence.", "examples": [ [ { "path": "/admin/*" } ], [ { "path": "/admin/*" }, { "method": "get", "path": "/admin/users" }, { "method": [ "get", "PURGE" ], "path": "/cache" } ] ], "items": { "additionalProperties": false, "properties": { "method": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" } ], "description": "Restrict this selector to one or more specific methods (a standard HTTP method, `query`, or a 3.2\n`additionalOperations` custom verb, matched case-sensitively). Omit to match every method on this path.", "title": "method" }, "path": { "description": "The path (or, for a webhook, the event name) to match, exactly as it appears in this input's own OpenAPI\ndocument -- before `pathModification` is applied. Supports a `*` wildcard: `/admin/*` matches every path\nstarting with `/admin/`.", "minLength": 1, "title": "path", "type": "string" } }, "required": [ "path" ], "type": "object" }, "title": "excludePaths", "type": "array" }, "excludeTags": { "description": "Any Operation that has any one of these tags will be excluded from the final result. If a single Operation contains\nan includeTag and an excludeTag then it will be excluded; exclusion takes precedence.", "items": { "type": "string" }, "title": "excludeTags", "type": "array" }, "includePaths": { "description": "Only Operations whose path (and, if given, method) matches one of these selectors will be taken from this\nOpenAPI file. `path` supports a `*` wildcard, matched the same way `includeTags`/`excludeTags` are. Selectors\nare matched against this input's own original path, before `pathModification` is applied. If an Operation is\nmatched by both `includePaths` and `includeTags` (or neither), both must pass for it to survive.", "examples": [ [ { "path": "/admin/*" } ], [ { "path": "/admin/*" }, { "method": "get", "path": "/admin/users" }, { "method": [ "get", "PURGE" ], "path": "/cache" } ] ], "items": { "additionalProperties": false, "properties": { "method": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" } ], "description": "Restrict this selector to one or more specific methods (a standard HTTP method, `query`, or a 3.2\n`additionalOperations` custom verb, matched case-sensitively). Omit to match every method on this path.", "title": "method" }, "path": { "description": "The path (or, for a webhook, the event name) to match, exactly as it appears in this input's own OpenAPI\ndocument -- before `pathModification` is applied. Supports a `*` wildcard: `/admin/*` matches every path\nstarting with `/admin/`.", "minLength": 1, "title": "path", "type": "string" } }, "required": [ "path" ], "type": "object" }, "title": "includePaths", "type": "array" }, "includeTags": { "description": "Only Operatinos that have these tags will be taken from this OpenAPI file. If a single Operation contains\nan includeTag and an excludeTag then it will be excluded; exclusion takes precedence.", "items": { "type": "string" }, "title": "includeTags", "type": "array" } }, "title": "__type_1", "type": "object" }, "__type_2": { "additionalProperties": false, "properties": { "append": { "default": false, "description": "Wether or not the description for this OpenAPI file will be merged into the description of the final file.", "title": "append", "type": "boolean" }, "title": { "$ref": "#/definitions/DescriptionTitle", "description": "You may optionally include a Markdown Title to demarcate this particular section of the merged description files.", "examples": [ { "value": "Title 1" }, { "headingLevel": 2, "value": "Title Level 2" }, { "headingLevel": 6, "value": "Inperceptible title" } ], "title": "title" } }, "required": [ "append" ], "title": "__type_2", "type": "object" }, "__type_3": { "additionalProperties": false, "properties": { "headingLevel": { "default": 1, "description": "What heading level this heading will be at: from h1 through to h6. The default value is 1 and will create h1 elements\nin Markdown format.", "maximum": 6, "minimum": 1, "title": "headingLevel", "type": "number" }, "value": { "description": "The value of the included title.", "minLength": 1, "title": "value", "type": "string" } }, "required": [ "value" ], "title": "__type_3", "type": "object" }, "__type_4": { "additionalProperties": false, "description": "A tag applied to every operation from one input.", "properties": { "description": { "description": "Description for the tag in the merged document's top-level `tags` array.\nFirst-wins if another input injects the same name.", "title": "description", "type": "string" }, "name": { "description": "The tag name to add.", "minLength": 1, "title": "name", "type": "string" } }, "required": [ "name" ], "title": "__type_4", "type": "object" }, "__type_5": { "additionalProperties": false, "description": "The subset of `info` worth overriding from a configuration file.\n\nDeliberately not the full Info object: `version` and `title` are the ones\npeople ask for, and description rounds it out. Kept narrow so the generated\nschema stays readable and `--noExtraProps` still catches typos.", "properties": { "description": { "title": "description", "type": "string" }, "title": { "minLength": 1, "title": "title", "type": "string" }, "version": { "minLength": 1, "title": "version", "type": "string" } }, "title": "__type_5", "type": "object" } }, "description": "The Configuration file for the OpenAPI Merge CLI Tool.", "properties": { "extensionMergeStrategies": { "additionalProperties": { "$ref": "#/definitions/ExtensionMergeNode" }, "description": "How to combine a document-root `x-*` extension's value across inputs,\nkeyed by extension name (issue #60, generalised as proposal 48).\n\nAn extension not mentioned here keeps the historical default: the first\ninput that declares it wins, unchanged. Only the document root is\ncovered -- `x-*` fields elsewhere (`info`, `tags`, path items,\n`components`) are not reached by this option. See {@link ExtensionMergeNode}.", "examples": [ { "x-tagGroups": { "item": { "fields": { "tags": { "kind": "array", "strategy": "concat-unique" } }, "kind": "object", "strategy": "merge" }, "key": "name", "kind": "array", "strategy": "union-by-key" } }, { "x-owner": { "kind": "scalar", "strategy": "error" } }, { "x-rate-limit-overrides": { "kind": "object", "strategy": "merge" }, "x-tagGroups": { "item": { "fields": { "tags": { "kind": "array", "strategy": "concat-unique" } }, "kind": "object", "strategy": "merge" }, "key": "name", "kind": "array", "strategy": "union-by-key" } } ], "title": "extensionMergeStrategies", "type": "object" }, "formatting": { "$ref": "#/definitions/OutputFormatting", "description": "Optional output-formatting controls (issue #114). When omitted, the\noutput is formatted with 2 spaces of indentation (the historical\ndefault).", "title": "formatting" }, "info": { "$ref": "#/definitions/ConfigurationInfoOverride", "description": "Override fields of the merged `info` object (issue #102).\n\nWithout this, `info` comes from the first input, so a merged document is\ntitled after whichever service happens to be listed first. Merged field by\nfield, so setting only `title` does not require restating `version`.", "title": "info" }, "inputRoot": { "description": "Optional defence-in-depth restriction, the read-side counterpart to\n`outputRoot` (proposal 38): when set, the CLI will refuse to read a\nlocal file -- whether a declared `inputFile` or a file discovered via\n`resolveExternalReferences` -- from anywhere outside this directory.\n\nAny local file load that would reach outside `inputRoot` is a hard\nerror: the merge does not proceed and no output is written, whether the\noffending path came from a declared `inputFile` or was reached\ntransitively by following a `$ref` out of some other document. Every\nviolation found is reported together, not just the first. The check\ncompares the realpath of the resolved input's nearest existing ancestor\nagainst the realpath of this root, so symlinks cannot be used to escape.\n\nApplies to local files only. `inputURL` and URLs discovered via\n`resolveExternalReferences` are a different trust boundary (network\negress, not filesystem containment) and are not affected by this option.\n\nLeave unset to keep the historical permissive default; this option is\nintended for embedded / multi-tenant uses of the CLI, or for configs\nwhose `resolveExternalReferences` inputs are not fully trusted.", "minLength": 1, "title": "inputRoot", "type": "string" }, "inputs": { "description": "The input items for the merge algorithm. You must provide at least one.", "examples": [ [ { "inputFile": "./swagger.json" }, { "inputURL": "https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json" } ], [ { "inputFile": "./swagger.json" }, { "inputURL": "https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json" }, { "description": { "append": true, "title": { "headingLevel": 1, "value": "My Swagger Description" } }, "dispute": { "alwaysApply": true, "suffix": "Model" }, "inputFile": "./swagger.json", "operationSelection": { "excludeTags": [ "private" ], "includeTags": [ "public" ] }, "pathModification": { "prepend": "/jira", "stripStart": "/rest" } } ] ], "items": { "$ref": "#/definitions/ConfigurationInput" }, "minItems": 1, "title": "inputs", "type": "array" }, "output": { "description": "The output file to put the results in. If you use the .yml or .yaml extension then the schema will be output\nin YAML format, otherwise, it will be output in JSON format.\n\nAny missing directories in this path are created automatically.", "minLength": 1, "title": "output", "type": "string" }, "outputRoot": { "description": "Optional defence-in-depth restriction (see issue #93 Security Considerations):\nwhen set, the CLI will refuse to write the merged spec anywhere outside this\ndirectory and will exit with `ExitCode.ErrorUnsafePath` (5). The check\ncompares the realpath of the resolved output's nearest existing ancestor\nagainst the realpath of this root, so symlinks cannot be used to escape.\n\nLeave unset to keep the historical permissive default; this option is\nintended for embedded / multi-tenant uses of the CLI where the\nconfiguration file may not be fully trusted.", "minLength": 1, "title": "outputRoot", "type": "string" }, "pruneUnusedComponents": { "description": "Drop components that nothing in the merged output references (issue #94).\n\nDefaults to false. Useful with `operationSelection`, where excluding tags\nremoves operations but would otherwise leave the schemas only those\noperations used behind. A component still referenced by another surviving\nendpoint is kept.\n\nOff by default because pruning is destructive: a document may carry\ndefinitions referenced only from outside it.", "title": "pruneUnusedComponents", "type": "boolean" }, "resolveExternalReferences": { "description": "Follow `$ref`s that point outside the declared inputs -- to a file or URL\nthis configuration never named -- and pull in just the specific\ncomponents they ask for (issue #10).\n\nDefaults to `false`. A `$ref` into one of the *declared* `inputs` is\nalways resolved correctly regardless of this setting (issue #104) --\nthat fix is unconditional, since it only ever affects a `$ref` that is\nalready broken today. This setting is what additionally lets a `$ref`\ndiscover and load documents nobody listed in `inputs`.\n\nOff by default because it changes what this tool reads: with it on, the\nfiles and URLs actually loaded are no longer limited to what `inputs`\nnames, transitively following wherever a `$ref` in *any* loaded document\npoints. Turn it on deliberately, for configurations whose inputs are\ntrusted to the same degree the config file itself is.\n\nA `$ref` this discovers but cannot load (missing file, failed fetch,\nunparseable content) is left exactly as written and logged as a warning\n-- not a hard failure, matching how a `$ref` into a declared input that\ncannot be resolved is also left untouched rather than erroring.", "title": "resolveExternalReferences", "type": "boolean" }, "securitySchemesStrategy": { "description": "How `components.securitySchemes` are combined across inputs (issue #33).\n\n- `merge` (default) -- combine them, exactly as every other component type\n is combined: identical definitions collapse, differing ones are renamed\n using the input's dispute prefix or a numeric suffix, and every security\n requirement naming a renamed scheme is rewritten to match.\n- `first` -- take the schemes from the first input that declares any and\n drop the rest. The behaviour before this option existed. Right for an API\n gateway, which owns authentication and does not want a backend's own\n scheme definitions in the published document -- but note that a later\n input's operations may then require a scheme the output does not define.\n- `error` -- combine them, but fail if two inputs define the same scheme\n name differently, rather than renaming around it. Identical definitions\n still collapse.", "enum": [ "error", "first", "merge" ], "title": "securitySchemesStrategy", "type": "string" }, "serversStrategy": { "description": "How to combine the top-level `servers` array across inputs (issue #4).\n\n- `first` (default) -- take the first input that declares `servers` and\n discard the rest. Correct for the API-gateway case this tool targets,\n where the gateway's URLs are canonical and a backend's own URLs are an\n implementation detail.\n- `concat` -- keep every input's servers, in input order, deduplicated by\n URL. For documenting several microservices in one file.", "enum": [ "concat", "first" ], "title": "serversStrategy", "type": "string" } }, "required": [ "inputs", "output" ], "type": "object", "$id": "https://github.com/robertmassaioli/openapi-merge/blob/main/packages/openapi-merge-cli/src/data.ts", "title": "Configuration" }