@speclynx/apidom-ns-openapi-2 4.0.5 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-ns-openapi-2",
-  "version": "4.0.5",
+  "version": "4.2.0",
   "description": "OpenAPI 2.0 namespace for ApiDOM.",
   "keywords": [
     "apidom",
@@ -56,11 +56,12 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.0.5",
-    "@speclynx/apidom-datamodel": "4.0.5",
-    "@speclynx/apidom-error": "4.0.5",
-    "@speclynx/apidom-ns-json-schema-draft-4": "4.0.5",
-    "@speclynx/apidom-traverse": "4.0.5",
+    "@speclynx/apidom-core": "4.2.0",
+    "@speclynx/apidom-datamodel": "4.2.0",
+    "@speclynx/apidom-error": "4.2.0",
+    "@speclynx/apidom-json-pointer": "4.2.0",
+    "@speclynx/apidom-ns-json-schema-draft-4": "4.2.0",
+    "@speclynx/apidom-traverse": "4.2.0",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0",
     "ts-mixer": "^6.0.4"
@@ -75,5 +76,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "5a85d2a832eeefb07d03760faa391b457447e966"
+  "gitHead": "3485d180340f2d4fad149bcf062a6f618030ca9b"
 }

package/src/index.cjs

@@ -3,8 +3,8 @@
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
-exports.refractLicense = exports.refractJSONReference = exports.refractItems = exports.refractInfo = exports.refractHeaders = exports.refractHeader = exports.refractExternalDocumentation = exports.refractExample = exports.refractDefinitions = exports.refractContact = exports.refract = exports.mediaTypes = exports.isXmlElement = exports.isTagElement = exports.isSwaggerVersionElement = exports.isSwaggerExtension = exports.isSwaggerElement = exports.isSecuritySchemeElement = exports.isSecurityRequirementElement = exports.isSecurityDefinitionsElement = exports.isScopesElement = exports.isSchemaElement = exports.isResponsesElement = exports.isResponsesDefinitionsElement = exports.isResponseElement = exports.isReferenceLikeElement = exports.isReferenceElement = exports.isPathsElement = exports.isPathItemElement = exports.isParametersDefinitionsElement = exports.isParameterElement = exports.isOperationElement = exports.isLicenseElement = exports.isJSONReferenceLikeElement = exports.isJSONReferenceElement = exports.isItemsElement = exports.isInfoElement = exports.isHeadersElement = exports.isHeaderElement = exports.isExternalDocumentationElement = exports.isExampleElement = exports.isDefinitionsElement = exports.isContactElement = exports.default = exports.XmlElement = exports.Visitor = exports.TagElement = exports.SwaggerVersionElement = exports.SwaggerTagsElement = exports.SwaggerSecurityElement = exports.SwaggerSchemesElement = exports.SwaggerProducesElement = exports.SwaggerElement = exports.SwaggerConsumesElement = exports.SpecificationVisitor = exports.SecuritySchemeElement = exports.SecurityRequirementElement = exports.SecurityDefinitionsElement = exports.ScopesElement = exports.SchemaElement = exports.ResponsesElement = exports.ResponsesDefinitionsElement = exports.ResponseElement = exports.ReferenceElement = exports.PatternedFieldsVisitor = exports.PathsElement = exports.PathItemParametersElement = exports.PathItemElement = exports.ParametersDefinitionsElement = exports.ParameterElement = exports.OperationTagsElement = exports.OperationSecurityElement = exports.OperationSchemesElement = exports.OperationProducesElement = exports.OperationParametersElement = exports.OperationElement = exports.OperationConsumesElement = exports.OpenAPIMediaTypes = exports.MixedFieldsVisitorBase = exports.MixedFieldsVisitor = exports.MapVisitor = exports.LicenseElement = exports.JSONReferenceElement = exports.ItemsElement = exports.InfoElement = exports.HeadersElement = exports.HeaderElement = exports.FixedFieldsVisitor = exports.FallbackVisitor = exports.ExternalDocumentationElement = exports.ExampleElement = exports.DefinitionsElement = exports.ContactElement = exports.BaseSpecificationVisitor = exports.BasePatternedFieldsVisitor = exports.BaseMixedFieldsVisitor = exports.BaseMapVisitor = exports.BaseFixedFieldsVisitor = exports.BaseAlternatingVisitor = exports.AlternatingVisitor = void 0;
-exports.specificationObj = exports.refractorPluginReplaceEmptyElement = exports.refractXml = exports.refractTag = exports.refractSwagger = exports.refractSecurityScheme = exports.refractSecurityRequirement = exports.refractSecurityDefinitions = exports.refractScopes = exports.refractSchema = exports.refractResponsesDefinitions = exports.refractResponses = exports.refractResponse = exports.refractReference = exports.refractPaths = exports.refractPathItem = exports.refractParametersDefinitions = exports.refractParameter = exports.refractOperation = void 0;
+exports.refractJSONReference = exports.refractItems = exports.refractInfo = exports.refractHeaders = exports.refractHeader = exports.refractExternalDocumentation = exports.refractExample = exports.refractDefinitions = exports.refractContact = exports.refract = exports.mediaTypes = exports.isXmlElement = exports.isTagElement = exports.isSwaggerVersionElement = exports.isSwaggerExtension = exports.isSwaggerElement = exports.isSecuritySchemeElement = exports.isSecurityRequirementElement = exports.isSecurityDefinitionsElement = exports.isScopesElement = exports.isSchemaElement = exports.isResponsesElement = exports.isResponsesDefinitionsElement = exports.isResponseElement = exports.isReferenceLikeElement = exports.isReferenceElement = exports.isPathsElement = exports.isPathItemElement = exports.isParametersDefinitionsElement = exports.isParameterElement = exports.isOperationElement = exports.isLicenseElement = exports.isJSONReferenceLikeElement = exports.isJSONReferenceElement = exports.isItemsElement = exports.isInfoElement = exports.isHeadersElement = exports.isHeaderElement = exports.isExternalDocumentationElement = exports.isExampleElement = exports.isDefinitionsElement = exports.isContactElement = exports.default = exports.createToolbox = exports.XmlElement = exports.Visitor = exports.TagElement = exports.SwaggerVersionElement = exports.SwaggerTagsElement = exports.SwaggerSecurityElement = exports.SwaggerSchemesElement = exports.SwaggerProducesElement = exports.SwaggerElement = exports.SwaggerConsumesElement = exports.SpecificationVisitor = exports.SecuritySchemeElement = exports.SecurityRequirementElement = exports.SecurityDefinitionsElement = exports.ScopesElement = exports.SchemaElement = exports.ResponsesElement = exports.ResponsesDefinitionsElement = exports.ResponseElement = exports.ReferenceElement = exports.PatternedFieldsVisitor = exports.PathsElement = exports.PathItemParametersElement = exports.PathItemElement = exports.ParametersDefinitionsElement = exports.ParameterElement = exports.OperationTagsElement = exports.OperationSecurityElement = exports.OperationSchemesElement = exports.OperationProducesElement = exports.OperationParametersElement = exports.OperationElement = exports.OperationConsumesElement = exports.OpenAPIMediaTypes = exports.MixedFieldsVisitorBase = exports.MixedFieldsVisitor = exports.MapVisitor = exports.LicenseElement = exports.JSONReferenceElement = exports.ItemsElement = exports.InfoElement = exports.HeadersElement = exports.HeaderElement = exports.FixedFieldsVisitor = exports.FallbackVisitor = exports.ExternalDocumentationElement = exports.ExampleElement = exports.DefinitionsElement = exports.ContactElement = exports.BaseSpecificationVisitor = exports.BasePatternedFieldsVisitor = exports.BaseMixedFieldsVisitor = exports.BaseMapVisitor = exports.BaseFixedFieldsVisitor = exports.BaseAlternatingVisitor = exports.AlternatingVisitor = void 0;
+exports.specificationObj = exports.refractorPluginReplaceEmptyElement = exports.refractorPluginNormalizeSecurityRequirements = exports.refractorPluginNormalizeParameters = exports.refractXml = exports.refractTag = exports.refractSwagger = exports.refractSecurityScheme = exports.refractSecurityRequirement = exports.refractSecurityDefinitions = exports.refractScopes = exports.refractSchema = exports.refractResponsesDefinitions = exports.refractResponses = exports.refractResponse = exports.refractReference = exports.refractPaths = exports.refractPathItem = exports.refractParametersDefinitions = exports.refractParameter = exports.refractOperation = exports.refractLicense = void 0;
 var _apidomNsJsonSchemaDraft = require("@speclynx/apidom-ns-json-schema-draft-4");
 exports.isJSONReferenceElement = _apidomNsJsonSchemaDraft.isJSONReferenceElement;
 exports.isJSONReferenceLikeElement = _apidomNsJsonSchemaDraft.isJSONReferenceLikeElement;
@@ -17,6 +17,10 @@ var _namespace = _interopRequireDefault(require("./namespace.cjs"));
 exports.default = _namespace.default;
 var _replaceEmptyElement = _interopRequireDefault(require("./refractor/plugins/replace-empty-element.cjs"));
 exports.refractorPluginReplaceEmptyElement = _replaceEmptyElement.default;
+var _normalizeParameters = _interopRequireDefault(require("./refractor/plugins/normalize-parameters.cjs"));
+exports.refractorPluginNormalizeParameters = _normalizeParameters.default;
+var _normalizeSecurityRequirements = _interopRequireDefault(require("./refractor/plugins/normalize-security-requirements.cjs"));
+exports.refractorPluginNormalizeSecurityRequirements = _normalizeSecurityRequirements.default;
 var _index = _interopRequireWildcard(require("./refractor/index.cjs"));
 exports.refract = _index.default;
 exports.refractSwagger = _index.refractSwagger;
@@ -45,6 +49,8 @@ exports.refractSecurityDefinitions = _index.refractSecurityDefinitions;
 exports.refractSecurityScheme = _index.refractSecurityScheme;
 exports.refractScopes = _index.refractScopes;
 exports.refractSecurityRequirement = _index.refractSecurityRequirement;
+var _toolbox = _interopRequireDefault(require("./refractor/toolbox.cjs"));
+exports.createToolbox = _toolbox.default;
 var _specification = _interopRequireDefault(require("./refractor/specification.cjs"));
 exports.specificationObj = _specification.default;
 var _predicates = require("./predicates.cjs");

package/src/index.mjs

@@ -2,7 +2,10 @@ export { isJSONReferenceElement, isJSONReferenceLikeElement, JSONReferenceElemen
 export { default as mediaTypes, OpenAPIMediaTypes } from "./media-types.mjs";
 export { default } from "./namespace.mjs";
 export { default as refractorPluginReplaceEmptyElement } from "./refractor/plugins/replace-empty-element.mjs";
+export { default as refractorPluginNormalizeParameters } from "./refractor/plugins/normalize-parameters.mjs";
+export { default as refractorPluginNormalizeSecurityRequirements } from "./refractor/plugins/normalize-security-requirements.mjs";
 export { default as refract, refractSwagger, refractInfo, refractContact, refractLicense, refractPaths, refractPathItem, refractOperation, refractExternalDocumentation, refractParameter, refractItems, refractResponses, refractResponse, refractHeaders, refractExample, refractHeader, refractTag, refractReference, refractSchema, refractXml, refractDefinitions, refractParametersDefinitions, refractResponsesDefinitions, refractSecurityDefinitions, refractSecurityScheme, refractScopes, refractSecurityRequirement } from "./refractor/index.mjs";
+export { default as createToolbox } from "./refractor/toolbox.mjs";
 export { default as specificationObj } from "./refractor/specification.mjs";
 export { isSwaggerElement, isSwaggerVersionElement, isInfoElement, isContactElement, isLicenseElement, isPathsElement, isPathItemElement, isOperationElement, isExternalDocumentationElement, isParameterElement, isItemsElement, isResponsesElement, isResponseElement, isHeadersElement, isExampleElement, isHeaderElement, isTagElement, isReferenceElement, isSchemaElement, isXmlElement, isDefinitionsElement, isParametersDefinitionsElement, isResponsesDefinitionsElement, isSecurityDefinitionsElement, isSecuritySchemeElement, isScopesElement, isSecurityRequirementElement } from "./predicates.mjs";
 export { isReferenceLikeElement, isSwaggerExtension } from "./refractor/predicates.mjs";

package/src/refractor/plugins/normalize-parameters.cjs

@@ -0,0 +1,108 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _OperationParameters = _interopRequireDefault(require("../../elements/nces/OperationParameters.cjs"));
+var _index = _interopRequireDefault(require("./normalize-storage/index.cjs"));
+var _predicates = require("../../predicates.cjs");
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for all the operations described under this path.
+ * These parameters can be overridden at the operation level, but cannot be removed there.
+ * The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * Establishes identity between two Parameter Objects.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * {@link https://spec.openapis.org/oas/v2.0.html#path-item-object}
+ */
+const parameterEquals = (parameter1, parameter2) => {
+  if (!(0, _predicates.isParameterElement)(parameter1)) return false;
+  if (!(0, _predicates.isParameterElement)(parameter2)) return false;
+  if (!(0, _apidomDatamodel.isStringElement)(parameter1.name)) return false;
+  if (!(0, _apidomDatamodel.isStringElement)(parameter1.in)) return false;
+  if (!(0, _apidomDatamodel.isStringElement)(parameter2.name)) return false;
+  if (!(0, _apidomDatamodel.isStringElement)(parameter2.in)) return false;
+  return (0, _apidomCore.toValue)(parameter1.name) === (0, _apidomCore.toValue)(parameter2.name) && (0, _apidomCore.toValue)(parameter1.in) === (0, _apidomCore.toValue)(parameter2.in);
+};
+
+/**
+ * Inherits parameters from a PathItem into an Operation element.
+ * Operation parameters take precedence; PathItem parameters are merged in
+ * for any (name, in) combination not already defined at the Operation level.
+ * @public
+ */
+const inheritParametersToOperation = (operationElement, pathItemElement) => {
+  const pathItemParams = (0, _apidomDatamodel.isArrayElement)(pathItemElement.parameters) ? [...pathItemElement.parameters] : [];
+  if (pathItemParams.length === 0) return;
+  const operationParams = (0, _apidomDatamodel.isArrayElement)(operationElement.parameters) ? [...operationElement.parameters] : [];
+
+  // prefers the first item if two items compare equal based on the predicate
+  const mergedParameters = (0, _ramda.uniqWith)(parameterEquals, [...operationParams, ...pathItemParams]);
+  operationElement.parameters = new _OperationParameters.default(mergedParameters);
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      SwaggerElement: {
+        enter(path) {
+          const element = path.node;
+          storage = new _index.default(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      OperationElement: {
+        leave(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes(); // parent to root order
+
+          // skip visiting this Operation if inside parameters definitions
+          if (ancestors.some(predicates.isParametersDefinitionsElement)) {
+            return;
+          }
+          const parentPathItemElement = ancestors.find(predicates.isPathItemElement);
+
+          // no parent Path Item to inherit from
+          if (!predicates.isPathItemElement(parentPathItemElement)) {
+            return;
+          }
+          const operationJSONPointer = path.formatPath();
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          inheritParametersToOperation(operationElement, parentPathItemElement);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+plugin.inheritParametersToOperation = inheritParametersToOperation;
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-parameters.mjs

@@ -0,0 +1,102 @@
+import { uniqWith } from 'ramda';
+import { toValue } from '@speclynx/apidom-core';
+import { isStringElement, isArrayElement } from '@speclynx/apidom-datamodel';
+import OperationParametersElement from "../../elements/nces/OperationParameters.mjs";
+import NormalizeStorage from "./normalize-storage/index.mjs";
+import { isParameterElement } from "../../predicates.mjs";
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for all the operations described under this path.
+ * These parameters can be overridden at the operation level, but cannot be removed there.
+ * The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * Establishes identity between two Parameter Objects.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * {@link https://spec.openapis.org/oas/v2.0.html#path-item-object}
+ */
+const parameterEquals = (parameter1, parameter2) => {
+  if (!isParameterElement(parameter1)) return false;
+  if (!isParameterElement(parameter2)) return false;
+  if (!isStringElement(parameter1.name)) return false;
+  if (!isStringElement(parameter1.in)) return false;
+  if (!isStringElement(parameter2.name)) return false;
+  if (!isStringElement(parameter2.in)) return false;
+  return toValue(parameter1.name) === toValue(parameter2.name) && toValue(parameter1.in) === toValue(parameter2.in);
+};
+
+/**
+ * Inherits parameters from a PathItem into an Operation element.
+ * Operation parameters take precedence; PathItem parameters are merged in
+ * for any (name, in) combination not already defined at the Operation level.
+ * @public
+ */
+const inheritParametersToOperation = (operationElement, pathItemElement) => {
+  const pathItemParams = isArrayElement(pathItemElement.parameters) ? [...pathItemElement.parameters] : [];
+  if (pathItemParams.length === 0) return;
+  const operationParams = isArrayElement(operationElement.parameters) ? [...operationElement.parameters] : [];
+
+  // prefers the first item if two items compare equal based on the predicate
+  const mergedParameters = uniqWith(parameterEquals, [...operationParams, ...pathItemParams]);
+  operationElement.parameters = new OperationParametersElement(mergedParameters);
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      SwaggerElement: {
+        enter(path) {
+          const element = path.node;
+          storage = new NormalizeStorage(element, storageField, 'parameters');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      OperationElement: {
+        leave(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes(); // parent to root order
+
+          // skip visiting this Operation if inside parameters definitions
+          if (ancestors.some(predicates.isParametersDefinitionsElement)) {
+            return;
+          }
+          const parentPathItemElement = ancestors.find(predicates.isPathItemElement);
+
+          // no parent Path Item to inherit from
+          if (!predicates.isPathItemElement(parentPathItemElement)) {
+            return;
+          }
+          const operationJSONPointer = path.formatPath();
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          inheritParametersToOperation(operationElement, parentPathItemElement);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+plugin.inheritParametersToOperation = inheritParametersToOperation;
+export default plugin;

package/src/refractor/plugins/normalize-security-requirements.cjs

@@ -0,0 +1,87 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _OperationSecurity = _interopRequireDefault(require("../../elements/nces/OperationSecurity.cjs"));
+var _index = _interopRequireDefault(require("./normalize-storage/index.cjs"));
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * Inherits top-level security requirements into an Operation element.
+ * If Operation.security is missing and Swagger.security is defined, copies it down.
+ * @public
+ */
+const inheritSecurityToOperation = (operationElement, swaggerElement) => {
+  const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+  const hasTopLevelSecurity = (0, _apidomDatamodel.isArrayElement)(swaggerElement.security);
+  if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+    operationElement.security = new _OperationSecurity.default([...swaggerElement.security]);
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      SwaggerElement: {
+        enter(path) {
+          const swaggerElement = path.node;
+          storage = new _index.default(swaggerElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(swaggerElement.security)) {
+            topLevelSecurity = swaggerElement.security;
+          }
+        },
+        leave() {
+          storage = undefined;
+          topLevelSecurity = undefined;
+        }
+      },
+      OperationElement: {
+        leave(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes(); // parent to root order
+
+          // skip visiting this Operation if inside parameters definitions
+          if (ancestors.some(predicates.isParametersDefinitionsElement)) {
+            return;
+          }
+          const operationJSONPointer = path.formatPath();
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+          const hasTopLevelSecurity = typeof topLevelSecurity !== 'undefined';
+          if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+            operationElement.security = new _OperationSecurity.default([...topLevelSecurity]);
+            storage.append(operationJSONPointer);
+          }
+        }
+      }
+    }
+  };
+};
+plugin.inheritSecurityToOperation = inheritSecurityToOperation;
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-security-requirements.mjs

@@ -0,0 +1,81 @@
+import { isArrayElement } from '@speclynx/apidom-datamodel';
+import OperationSecurityElement from "../../elements/nces/OperationSecurity.mjs";
+import NormalizeStorage from "./normalize-storage/index.mjs";
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * Inherits top-level security requirements into an Operation element.
+ * If Operation.security is missing and Swagger.security is defined, copies it down.
+ * @public
+ */
+const inheritSecurityToOperation = (operationElement, swaggerElement) => {
+  const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+  const hasTopLevelSecurity = isArrayElement(swaggerElement.security);
+  if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+    operationElement.security = new OperationSecurityElement([...swaggerElement.security]);
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      SwaggerElement: {
+        enter(path) {
+          const swaggerElement = path.node;
+          storage = new NormalizeStorage(swaggerElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(swaggerElement.security)) {
+            topLevelSecurity = swaggerElement.security;
+          }
+        },
+        leave() {
+          storage = undefined;
+          topLevelSecurity = undefined;
+        }
+      },
+      OperationElement: {
+        leave(path) {
+          const operationElement = path.node;
+          const ancestors = path.getAncestorNodes(); // parent to root order
+
+          // skip visiting this Operation if inside parameters definitions
+          if (ancestors.some(predicates.isParametersDefinitionsElement)) {
+            return;
+          }
+          const operationJSONPointer = path.formatPath();
+
+          // skip visiting this Operation Object if it's already normalized
+          if (storage.includes(operationJSONPointer)) {
+            return;
+          }
+          const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+          const hasTopLevelSecurity = typeof topLevelSecurity !== 'undefined';
+          if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+            operationElement.security = new OperationSecurityElement([...topLevelSecurity]);
+            storage.append(operationJSONPointer);
+          }
+        }
+      }
+    }
+  };
+};
+plugin.inheritSecurityToOperation = inheritSecurityToOperation;
+export default plugin;

package/src/refractor/plugins/normalize-storage/index.cjs

@@ -0,0 +1,38 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (this.internalStore === undefined) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!(0, _apidomDatamodel.isObjectElement)(rootStore)) {
+        rootStore = new _apidomDatamodel.ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!(0, _apidomDatamodel.isArrayElement)(store)) {
+        store = new _apidomDatamodel.ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+var _default = exports.default = NormalizeStorage;

package/src/refractor/plugins/normalize-storage/index.mjs

@@ -0,0 +1,34 @@
+import { ArrayElement, ObjectElement, isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
+class NormalizeStorage {
+  internalStore;
+  constructor(storageElement, storageField, storageSubField) {
+    this.storageElement = storageElement;
+    this.storageField = storageField;
+    this.storageSubField = storageSubField;
+  }
+  get store() {
+    if (this.internalStore === undefined) {
+      let rootStore = this.storageElement.get(this.storageField);
+      if (!isObjectElement(rootStore)) {
+        rootStore = new ObjectElement();
+        this.storageElement.set(this.storageField, rootStore);
+      }
+      let store = rootStore.get(this.storageSubField);
+      if (!isArrayElement(store)) {
+        store = new ArrayElement();
+        rootStore.set(this.storageSubField, store);
+      }
+      this.internalStore = store;
+    }
+    return this.internalStore;
+  }
+  append(pointer) {
+    if (!this.includes(pointer)) {
+      this.store.push(pointer);
+    }
+  }
+  includes(pointer) {
+    return this.store.includes(pointer);
+  }
+}
+export default NormalizeStorage;

package/src/refractor/toolbox.cjs

@@ -12,12 +12,17 @@ var _namespace = _interopRequireDefault(require("../namespace.cjs"));
  * @public
  */
 
+/**
+ * @public
+ */
 const createToolbox = () => {
   const namespace = new _apidomDatamodel.Namespace();
   const predicates = {
     ...refractorPredicates,
     ...openApi2Predicates,
-    isStringElement: _apidomDatamodel.isStringElement
+    isStringElement: _apidomDatamodel.isStringElement,
+    isArrayElement: _apidomDatamodel.isArrayElement,
+    isObjectElement: _apidomDatamodel.isObjectElement
   };
   namespace.use(_namespace.default);
   return {

package/src/refractor/toolbox.mjs

@@ -1,7 +1,10 @@
-import { isStringElement, Namespace } from '@speclynx/apidom-datamodel';
+import { isStringElement, isArrayElement, isObjectElement, Namespace } from '@speclynx/apidom-datamodel';
 import * as openApi2Predicates from "../predicates.mjs";
 import * as refractorPredicates from "./predicates.mjs";
 import openApi2Namespace from "../namespace.mjs";
+/**
+ * @public
+ */
 /**
  * @public
  */
@@ -10,7 +13,9 @@ const createToolbox = () => {
   const predicates = {
     ...refractorPredicates,
     ...openApi2Predicates,
-    isStringElement
+    isStringElement,
+    isArrayElement,
+    isObjectElement
   };
   namespace.use(openApi2Namespace);
   return {

package/types/apidom-ns-openapi-2.d.ts

@@ -208,6 +208,11 @@ export declare class ContactVisitor extends BaseFixedFieldsVisitor {
     constructor(options: BaseFixedFieldsVisitorOptions);
 }
 
+/**
+ * @public
+ */
+export declare const createToolbox: () => Toolbox;
+
 /**
  * @public
  */
@@ -1270,6 +1275,74 @@ export declare type RefractorPlugin = (toolbox: Toolbox) => {
     post?: () => void;
 };
 
+/**
+ * @public
+ */
+export declare const refractorPluginNormalizeParameters: {
+    ({ storageField }?: RefractorPluginNormalizeParametersOptions): (toolbox: Toolbox) => {
+        visitor: {
+            SwaggerElement: {
+                enter(path: Path<SwaggerElement>): void;
+                leave(): void;
+            };
+            OperationElement: {
+                leave(path: Path<OperationElement>): void;
+            };
+        };
+    };
+    inheritParametersToOperation: (operationElement: OperationElement, pathItemElement: PathItemElement) => void;
+};
+
+/**
+ * Inheritance of Parameter Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for all the operations described under this path.
+ * These parameters can be overridden at the operation level, but cannot be removed there.
+ * The list MUST NOT include duplicated parameters.
+ * A unique parameter is defined by a combination of a name and location.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+export declare interface RefractorPluginNormalizeParametersOptions {
+    storageField?: string;
+}
+
+/**
+ * @public
+ */
+export declare const refractorPluginNormalizeSecurityRequirements: {
+    ({ storageField }?: RefractorPluginNormalizeSecurityRequirementsOptions): (toolbox: Toolbox) => {
+        visitor: {
+            SwaggerElement: {
+                enter(path: Path<SwaggerElement>): void;
+                leave(): void;
+            };
+            OperationElement: {
+                leave(path: Path<OperationElement>): void;
+            };
+        };
+    };
+    inheritSecurityToOperation: (operationElement: OperationElement, swaggerElement: SwaggerElement) => void;
+};
+
+/**
+ * Override of Security Requirement Objects.
+ *
+ * OpenAPI 2.0 specification excerpt that defines the override behavior:
+ *
+ * Operation.security definition overrides any declared top-level security.
+ * To remove a top-level security declaration, an empty array can be used.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+export declare interface RefractorPluginNormalizeSecurityRequirementsOptions {
+    storageField?: string;
+}
+
 /**
  * @public
  */