@speclynx/apidom-ns-openapi-3-0 4.0.5 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-ns-openapi-3-0",
-  "version": "4.0.5",
+  "version": "4.2.0",
   "description": "OpenAPI 3.0.x 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.isReferenceElement = exports.isPathsElement = exports.isPathItemElement = exports.isParameterElement = exports.isOperationElement = exports.isOpenapiElement = exports.isOpenApiExtension = exports.isOpenApi3_0Element = exports.isMediaTypeElement = exports.isLinkElement = exports.isLicenseElement = exports.isInfoElement = exports.isExternalDocumentationElement = exports.isExampleElement = exports.isContactElement = exports.isComponentsElement = exports.isCallbackElement = exports.default = exports.XmlElement = exports.Visitor = exports.TagsElement = exports.TagElement = exports.SpecificationVisitor = exports.SpecificationExtensionVisitor = exports.ServersElement = exports.ServerVariablesElement = exports.ServerVariableElement = exports.ServerElement = exports.SecuritySchemeElement = exports.SecurityRequirementElement = exports.SecurityElement = exports.SchemaElement = exports.ResponsesElement = exports.ResponseLinksElement = exports.ResponseHeadersElement = exports.ResponseElement = exports.ResponseContentElement = exports.RequestBodyElement = exports.RequestBodyContentElement = exports.ReferenceElement = exports.PatternedFieldsVisitor = exports.PathsElement = exports.PathItemServersElement = exports.PathItemParametersElement = exports.PathItemElement = exports.ParameterExamplesElement = exports.ParameterElement = exports.ParameterContentElement = exports.OperationTagsElement = exports.OperationServersElement = exports.OperationSecurityElement = exports.OperationParametersElement = exports.OperationElement = exports.OperationCallbacksElement = exports.OpenapiElement = exports.OpenApi3_0Element = exports.OpenAPIMediaTypes = exports.OAuthFlowsElement = exports.OAuthFlowScopesElement = exports.OAuthFlowElement = exports.MixedFieldsVisitorBase = exports.MixedFieldsVisitor = exports.MediaTypeExamplesElement = exports.MediaTypeEncodingElement = exports.MediaTypeElement = exports.MapVisitor = exports.LinkParametersElement = exports.LinkElement = exports.LicenseElement = exports.InfoElement = exports.HeaderExamplesElement = exports.HeaderElement = exports.HeaderContentElement = exports.FixedFieldsVisitor = exports.FallbackVisitor = exports.ExternalDocumentationElement = exports.ExampleElement = exports.EncodingHeadersElement = exports.EncodingElement = exports.DiscriminatorMappingElement = exports.DiscriminatorElement = exports.ContactElement = exports.ComponentsSecuritySchemesElement = exports.ComponentsSchemasElement = exports.ComponentsResponsesElement = exports.ComponentsRequestBodiesElement = exports.ComponentsParametersElement = exports.ComponentsLinksElement = exports.ComponentsHeadersElement = exports.ComponentsExamplesElement = exports.ComponentsElement = exports.ComponentsCallbacksElement = exports.CallbackElement = 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.refractServerVariable = exports.refractServer = exports.refractSecurityScheme = exports.refractSecurityRequirement = exports.refractSchema = exports.refractResponses = exports.refractResponse = exports.refractRequestBody = exports.refractReference = exports.refractPaths = exports.refractPathItem = exports.refractParameter = exports.refractOperation = exports.refractOpenApi3_0 = exports.refractOAuthFlows = exports.refractOAuthFlow = exports.refractMediaType = exports.refractLink = exports.refractLicense = exports.refractInfo = exports.refractHeader = exports.refractExternalDocumentation = exports.refractExample = exports.refractEncoding = exports.refractDiscriminator = exports.refractContact = exports.refractComponents = exports.refractCallback = exports.refract = exports.mediaTypes = exports.isTagLikeElement = exports.isServersElement = exports.isServerVariableElement = exports.isServerLikeElement = exports.isServerElement = exports.isSecuritySchemeElement = exports.isSecurityRequirementElement = exports.isSchemaElement = exports.isResponsesElement = exports.isResponseElement = exports.isRequestBodyElement = exports.isReferenceLikeElement = void 0;
+exports.isPathsElement = exports.isPathItemElement = exports.isParameterElement = exports.isOperationElement = exports.isOpenapiElement = exports.isOpenApiExtension = exports.isOpenApi3_0Element = exports.isMediaTypeElement = exports.isLinkElement = exports.isLicenseElement = exports.isInfoElement = exports.isExternalDocumentationElement = exports.isExampleElement = exports.isContactElement = exports.isComponentsElement = exports.isCallbackElement = exports.default = exports.createToolbox = exports.XmlElement = exports.Visitor = exports.TagsElement = exports.TagElement = exports.SpecificationVisitor = exports.SpecificationExtensionVisitor = exports.ServersElement = exports.ServerVariablesElement = exports.ServerVariableElement = exports.ServerElement = exports.SecuritySchemeElement = exports.SecurityRequirementElement = exports.SecurityElement = exports.SchemaElement = exports.ResponsesElement = exports.ResponseLinksElement = exports.ResponseHeadersElement = exports.ResponseElement = exports.ResponseContentElement = exports.RequestBodyElement = exports.RequestBodyContentElement = exports.ReferenceElement = exports.PatternedFieldsVisitor = exports.PathsElement = exports.PathItemServersElement = exports.PathItemParametersElement = exports.PathItemElement = exports.ParameterExamplesElement = exports.ParameterElement = exports.ParameterContentElement = exports.OperationTagsElement = exports.OperationServersElement = exports.OperationSecurityElement = exports.OperationParametersElement = exports.OperationElement = exports.OperationCallbacksElement = exports.OpenapiElement = exports.OpenApi3_0Element = exports.OpenAPIMediaTypes = exports.OAuthFlowsElement = exports.OAuthFlowScopesElement = exports.OAuthFlowElement = exports.MixedFieldsVisitorBase = exports.MixedFieldsVisitor = exports.MediaTypeExamplesElement = exports.MediaTypeEncodingElement = exports.MediaTypeElement = exports.MapVisitor = exports.LinkParametersElement = exports.LinkElement = exports.LicenseElement = exports.InfoElement = exports.HeaderExamplesElement = exports.HeaderElement = exports.HeaderContentElement = exports.FixedFieldsVisitor = exports.FallbackVisitor = exports.ExternalDocumentationElement = exports.ExampleElement = exports.EncodingHeadersElement = exports.EncodingElement = exports.DiscriminatorMappingElement = exports.DiscriminatorElement = exports.ContactElement = exports.ComponentsSecuritySchemesElement = exports.ComponentsSchemasElement = exports.ComponentsResponsesElement = exports.ComponentsRequestBodiesElement = exports.ComponentsParametersElement = exports.ComponentsLinksElement = exports.ComponentsHeadersElement = exports.ComponentsExamplesElement = exports.ComponentsElement = exports.ComponentsCallbacksElement = exports.CallbackElement = exports.BaseSpecificationVisitor = exports.BasePatternedFieldsVisitor = exports.BaseMixedFieldsVisitor = exports.BaseMapVisitor = exports.BaseFixedFieldsVisitor = exports.BaseAlternatingVisitor = exports.AlternatingVisitor = void 0;
+exports.specificationObj = exports.refractorPluginReplaceEmptyElement = exports.refractorPluginNormalizeServers = exports.refractorPluginNormalizeSecurityRequirements = exports.refractorPluginNormalizeParameters = exports.refractXml = exports.refractTag = exports.refractServerVariable = exports.refractServer = exports.refractSecurityScheme = exports.refractSecurityRequirement = exports.refractSchema = exports.refractResponses = exports.refractResponse = exports.refractRequestBody = exports.refractReference = exports.refractPaths = exports.refractPathItem = exports.refractParameter = exports.refractOperation = exports.refractOpenApi3_0 = exports.refractOAuthFlows = exports.refractOAuthFlow = exports.refractMediaType = exports.refractLink = exports.refractLicense = exports.refractInfo = exports.refractHeader = exports.refractExternalDocumentation = exports.refractExample = exports.refractEncoding = exports.refractDiscriminator = exports.refractContact = exports.refractComponents = exports.refractCallback = exports.refract = exports.mediaTypes = exports.isTagLikeElement = exports.isServersElement = exports.isServerVariableElement = exports.isServerLikeElement = exports.isServerElement = exports.isSecuritySchemeElement = exports.isSecurityRequirementElement = exports.isSchemaElement = exports.isResponsesElement = exports.isResponseElement = exports.isRequestBodyElement = exports.isReferenceLikeElement = exports.isReferenceElement = void 0;
 var _mediaTypes = _interopRequireWildcard(require("./media-types.cjs"));
 exports.mediaTypes = _mediaTypes.default;
 exports.OpenAPIMediaTypes = _mediaTypes.OpenAPIMediaTypes;
@@ -12,6 +12,12 @@ 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 _normalizeServers = _interopRequireDefault(require("./refractor/plugins/normalize-servers.cjs"));
+exports.refractorPluginNormalizeServers = _normalizeServers.default;
 var _index = _interopRequireWildcard(require("./refractor/index.cjs"));
 exports.refract = _index.default;
 exports.refractOpenApi3_0 = _index.refractOpenApi3_0;
@@ -44,6 +50,8 @@ exports.refractSecurityScheme = _index.refractSecurityScheme;
 exports.refractOAuthFlows = _index.refractOAuthFlows;
 exports.refractOAuthFlow = _index.refractOAuthFlow;
 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

@@ -1,7 +1,11 @@
 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 refractorPluginNormalizeServers } from "./refractor/plugins/normalize-servers.mjs";
 export { default as refract, refractOpenApi3_0, refractInfo, refractContact, refractLicense, refractServer, refractServerVariable, refractComponents, refractPaths, refractPathItem, refractOperation, refractExternalDocumentation, refractParameter, refractRequestBody, refractMediaType, refractEncoding, refractResponses, refractResponse, refractCallback, refractExample, refractLink, refractHeader, refractTag, refractReference, refractSchema, refractDiscriminator, refractXml, refractSecurityScheme, refractOAuthFlows, refractOAuthFlow, refractSecurityRequirement } from "./refractor/index.mjs";
+export { default as createToolbox } from "./refractor/toolbox.mjs";
 export { default as specificationObj } from "./refractor/specification.mjs";
 export { isCallbackElement, isComponentsElement, isContactElement, isExampleElement, isExternalDocumentationElement, isInfoElement, isLicenseElement, isLinkElement, isOpenapiElement, isOpenApi3_0Element, isOperationElement, isParameterElement, isPathItemElement, isPathsElement, isReferenceElement, isRequestBodyElement, isResponseElement, isResponsesElement, isSchemaElement, isSecurityRequirementElement, isSecuritySchemeElement, isServerElement, isServerVariableElement, isMediaTypeElement, isServersElement } from "./predicates.mjs";
 export { isReferenceLikeElement, isServerLikeElement, isTagLikeElement, isOpenApiExtension } from "./refractor/predicates.mjs";

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

@@ -0,0 +1,107 @@
+"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 3.0 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item,
+ * the new definition will override it but can never remove it. 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/v3.0.4.html#operation-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: {
+      OpenApi3_0Element: {
+        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 (ancestors.some(predicates.isComponentsElement)) {
+            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,101 @@
+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 3.0 specification excerpt that defines the inheritance behavior:
+ *
+ * A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item,
+ * the new definition will override it but can never remove it. 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/v3.0.4.html#operation-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: {
+      OpenApi3_0Element: {
+        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 (ancestors.some(predicates.isComponentsElement)) {
+            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,89 @@
+"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 3.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.
+ * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
+ * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * Inherits top-level security requirements into an Operation element.
+ * If Operation.security is missing and OpenAPI.security is defined, copies it down.
+ * @public
+ */
+const inheritSecurityToOperation = (operationElement, openapiElement) => {
+  const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+  const hasTopLevelSecurity = (0, _apidomDatamodel.isArrayElement)(openapiElement.security);
+  if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+    operationElement.security = new _OperationSecurity.default([...openapiElement.security]);
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_0Element: {
+        enter(path) {
+          const openapiElement = path.node;
+          storage = new _index.default(openapiElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(openapiElement.security)) {
+            topLevelSecurity = openapiElement.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 (ancestors.some(predicates.isComponentsElement)) {
+            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,83 @@
+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 3.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.
+ * When a list of Security Requirement Objects is defined on the OpenAPI Object or Operation Object,
+ * only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * Inherits top-level security requirements into an Operation element.
+ * If Operation.security is missing and OpenAPI.security is defined, copies it down.
+ * @public
+ */
+const inheritSecurityToOperation = (operationElement, openapiElement) => {
+  const missingOperationLevelSecurity = typeof operationElement.security === 'undefined';
+  const hasTopLevelSecurity = isArrayElement(openapiElement.security);
+  if (missingOperationLevelSecurity && hasTopLevelSecurity) {
+    operationElement.security = new OperationSecurityElement([...openapiElement.security]);
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let topLevelSecurity;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_0Element: {
+        enter(path) {
+          const openapiElement = path.node;
+          storage = new NormalizeStorage(openapiElement, storageField, 'security-requirements');
+          if (predicates.isArrayElement(openapiElement.security)) {
+            topLevelSecurity = openapiElement.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 (ancestors.some(predicates.isComponentsElement)) {
+            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-servers.cjs

@@ -0,0 +1,149 @@
+"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 _Servers = _interopRequireDefault(require("../../elements/nces/Servers.cjs"));
+var _PathItemServers = _interopRequireDefault(require("../../elements/nces/PathItemServers.cjs"));
+var _OperationServers = _interopRequireDefault(require("../../elements/nces/OperationServers.cjs"));
+var _index = _interopRequireDefault(require("./normalize-storage/index.cjs"));
+var _index2 = require("../index.cjs");
+/**
+ * Override of Server Objects.
+ *
+ * List of Server Objects can be defined in OpenAPI 3.0 on multiple levels:
+ *
+ *  - OpenAPI.servers
+ *  - PathItem.servers
+ *  - Operation.servers
+ *
+ * If a servers array is specified at the OpenAPI Object level, it will be overridden by `PathItem`.servers.
+ * If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by Operation.servers.
+ * @public
+ */
+
+/**
+ * Ensures the OpenAPI document has at least one server defined.
+ * If `servers` is missing or empty, adds a default server with `url: "/"`.
+ * @public
+ */
+const ensureDefaultServer = openapiElement => {
+  const isServersUndefined = typeof openapiElement.servers === 'undefined';
+  const isServersArray = (0, _apidomDatamodel.isArrayElement)(openapiElement.servers);
+  const isServersEmpty = isServersArray && openapiElement.servers.length === 0;
+  const defaultServer = (0, _index2.refractServer)({
+    url: '/'
+  });
+  if (isServersUndefined || !isServersArray) {
+    openapiElement.servers = new _Servers.default([defaultServer]);
+  } else if (isServersArray && isServersEmpty) {
+    openapiElement.servers.push(defaultServer);
+  }
+};
+
+/**
+ * Inherits servers from the OpenAPI root into a PathItem element.
+ * If PathItem.servers is missing or empty, copies from OpenAPI.servers.
+ * @public
+ */
+const inheritServersToPathItem = (pathItemElement, openapiElement) => {
+  const isServersUndefined = typeof pathItemElement.servers === 'undefined';
+  const isServersArray = (0, _apidomDatamodel.isArrayElement)(pathItemElement.servers);
+  const isServersEmpty = isServersArray && pathItemElement.servers.length === 0;
+  const openapiServers = [...(openapiElement.servers ?? [])];
+  if (isServersUndefined || !isServersArray) {
+    pathItemElement.servers = new _PathItemServers.default(openapiServers);
+  } else if (isServersArray && isServersEmpty) {
+    openapiServers.forEach(server => {
+      pathItemElement.servers.push(server);
+    });
+  }
+};
+
+/**
+ * Inherits servers from a PathItem into an Operation element.
+ * If Operation.servers is missing or empty, copies from PathItem.servers.
+ * @public
+ */
+const inheritServersToOperation = (operationElement, pathItemElement) => {
+  const isServersUndefined = typeof operationElement.servers === 'undefined';
+  const isServersArray = (0, _apidomDatamodel.isArrayElement)(operationElement.servers);
+  const isServersEmpty = isServersArray && operationElement.servers.length === 0;
+  const pathItemServers = [...(pathItemElement.servers ?? [])];
+  if (isServersUndefined || !isServersArray) {
+    operationElement.servers = new _OperationServers.default(pathItemServers);
+  } else if (isServersArray && isServersEmpty) {
+    pathItemServers.forEach(server => {
+      operationElement.servers.push(server);
+    });
+  }
+};
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_0Element: {
+        enter(path) {
+          const openapiElement = path.node;
+          ensureDefaultServer(openapiElement);
+          storage = new _index.default(openapiElement, storageField, 'servers');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      PathItemElement(path) {
+        const pathItemElement = path.node;
+        const ancestors = path.getAncestorNodes(); // parent to root order
+
+        // skip visiting this Path Item
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_0Element)) return;
+        const pathItemJSONPointer = path.formatPath();
+
+        // skip visiting this Path Item Object if it's already normalized
+        if (storage.includes(pathItemJSONPointer)) {
+          return;
+        }
+        const parentOpenapiElement = ancestors.find(predicates.isOpenApi3_0Element);
+        if (predicates.isOpenApi3_0Element(parentOpenapiElement)) {
+          inheritServersToPathItem(pathItemElement, parentOpenapiElement);
+          storage.append(pathItemJSONPointer);
+        }
+      },
+      OperationElement(path) {
+        const operationElement = path.node;
+        const ancestors = path.getAncestorNodes(); // parent to root order
+
+        // skip visiting this Operation
+        if (ancestors.some(predicates.isComponentsElement)) return;
+        if (!ancestors.some(predicates.isOpenApi3_0Element)) return;
+        const operationJSONPointer = path.formatPath();
+
+        // skip visiting this Operation Object if it's already normalized
+        if (storage.includes(operationJSONPointer)) {
+          return;
+        }
+        const parentPathItemElement = ancestors.find(predicates.isPathItemElement);
+        if (predicates.isPathItemElement(parentPathItemElement)) {
+          inheritServersToOperation(operationElement, parentPathItemElement);
+          storage.append(operationJSONPointer);
+        }
+      }
+    }
+  };
+};
+plugin.ensureDefaultServer = ensureDefaultServer;
+plugin.inheritServersToPathItem = inheritServersToPathItem;
+plugin.inheritServersToOperation = inheritServersToOperation;
+var _default = exports.default = plugin;