@speclynx/apidom-ns-openapi-3-1 4.0.2 → 4.0.4

package/src/refractor/inspect.cjs

@@ -0,0 +1,207 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+var _apidomCore = require("@speclynx/apidom-core");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _Callback = _interopRequireDefault(require("../elements/Callback.cjs"));
+exports.CallbackElement = _Callback.default;
+var _Components = _interopRequireDefault(require("../elements/Components.cjs"));
+exports.ComponentsElement = _Components.default;
+var _Contact = _interopRequireDefault(require("../elements/Contact.cjs"));
+exports.ContactElement = _Contact.default;
+var _Discriminator = _interopRequireDefault(require("../elements/Discriminator.cjs"));
+exports.DiscriminatorElement = _Discriminator.default;
+var _Encoding = _interopRequireDefault(require("../elements/Encoding.cjs"));
+exports.EncodingElement = _Encoding.default;
+var _Example = _interopRequireDefault(require("../elements/Example.cjs"));
+exports.ExampleElement = _Example.default;
+var _ExternalDocumentation = _interopRequireDefault(require("../elements/ExternalDocumentation.cjs"));
+exports.ExternalDocumentationElement = _ExternalDocumentation.default;
+var _Header = _interopRequireDefault(require("../elements/Header.cjs"));
+exports.HeaderElement = _Header.default;
+var _Info = _interopRequireDefault(require("../elements/Info.cjs"));
+exports.InfoElement = _Info.default;
+var _JsonSchemaDialect = _interopRequireDefault(require("../elements/JsonSchemaDialect.cjs"));
+exports.JsonSchemaDialectElement = _JsonSchemaDialect.default;
+var _License = _interopRequireDefault(require("../elements/License.cjs"));
+exports.LicenseElement = _License.default;
+var _Link = _interopRequireDefault(require("../elements/Link.cjs"));
+exports.LinkElement = _Link.default;
+var _MediaType = _interopRequireDefault(require("../elements/MediaType.cjs"));
+exports.MediaTypeElement = _MediaType.default;
+var _OAuthFlow = _interopRequireDefault(require("../elements/OAuthFlow.cjs"));
+exports.OAuthFlowElement = _OAuthFlow.default;
+var _OAuthFlows = _interopRequireDefault(require("../elements/OAuthFlows.cjs"));
+exports.OAuthFlowsElement = _OAuthFlows.default;
+var _Openapi = _interopRequireDefault(require("../elements/Openapi.cjs"));
+exports.OpenapiElement = _Openapi.default;
+var _OpenApi = _interopRequireDefault(require("../elements/OpenApi3-1.cjs"));
+exports.OpenApi3_1Element = _OpenApi.default;
+var _Operation = _interopRequireDefault(require("../elements/Operation.cjs"));
+exports.OperationElement = _Operation.default;
+var _Parameter = _interopRequireDefault(require("../elements/Parameter.cjs"));
+exports.ParameterElement = _Parameter.default;
+var _PathItem = _interopRequireDefault(require("../elements/PathItem.cjs"));
+exports.PathItemElement = _PathItem.default;
+var _Paths = _interopRequireDefault(require("../elements/Paths.cjs"));
+exports.PathsElement = _Paths.default;
+var _Reference = _interopRequireDefault(require("../elements/Reference.cjs"));
+exports.ReferenceElement = _Reference.default;
+var _RequestBody = _interopRequireDefault(require("../elements/RequestBody.cjs"));
+exports.RequestBodyElement = _RequestBody.default;
+var _Response = _interopRequireDefault(require("../elements/Response.cjs"));
+exports.ResponseElement = _Response.default;
+var _Responses = _interopRequireDefault(require("../elements/Responses.cjs"));
+exports.ResponsesElement = _Responses.default;
+var _Schema = _interopRequireDefault(require("../elements/Schema.cjs"));
+exports.SchemaElement = _Schema.default;
+var _SecurityRequirement = _interopRequireDefault(require("../elements/SecurityRequirement.cjs"));
+exports.SecurityRequirementElement = _SecurityRequirement.default;
+var _SecurityScheme = _interopRequireDefault(require("../elements/SecurityScheme.cjs"));
+exports.SecuritySchemeElement = _SecurityScheme.default;
+var _Server = _interopRequireDefault(require("../elements/Server.cjs"));
+exports.ServerElement = _Server.default;
+var _ServerVariable = _interopRequireDefault(require("../elements/ServerVariable.cjs"));
+exports.ServerVariableElement = _ServerVariable.default;
+var _Tag = _interopRequireDefault(require("../elements/Tag.cjs"));
+exports.TagElement = _Tag.default;
+var _Xml = _interopRequireDefault(require("../elements/Xml.cjs"));
+exports.XmlElement = _Xml.default;
+var _specification = _interopRequireDefault(require("./specification.cjs"));
+/**
+ * OpenAPI 3.1 specification elements.
+ */
+
+/**
+ * @public
+ */
+
+// Resolve specification to dereference $ref pointers
+const resolvedSpec = (0, _apidomCore.resolveSpecification)(_specification.default);
+
+// Extract fixed fields as list of { name, alias?, $visitor }
+const getFixedFields = fixedFieldsSpec => {
+  return Object.entries(fixedFieldsSpec).map(([name, fieldSpec]) => {
+    if ((0, _ramdaAdjunct.isPlainObject)(fieldSpec)) {
+      return {
+        name,
+        ...fieldSpec
+      };
+    }
+    return {
+      name,
+      $visitor: fieldSpec
+    };
+  });
+};
+
+// OpenAPI 3.1 specification elements
+Object.defineProperty(_OpenApi.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OpenApi.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Info.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Info.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Contact.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Contact.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_License.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.License.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Server.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Server.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_ServerVariable.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.ServerVariable.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Components.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Components.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_PathItem.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.PathItem.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Operation.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Operation.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_ExternalDocumentation.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.ExternalDocumentation.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Parameter.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Parameter.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_RequestBody.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.RequestBody.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_MediaType.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.MediaType.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Encoding.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Encoding.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Responses.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Responses.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Response.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Response.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Example.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Example.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Link.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Link.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Header.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Header.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Tag.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Tag.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Reference.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Reference.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Schema.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Schema.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Discriminator.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Discriminator.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_Xml.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.XML.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_SecurityScheme.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.SecurityScheme.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_OAuthFlows.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OAuthFlows.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(_OAuthFlow.default, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OAuthFlow.fixedFields),
+  enumerable: true
+});

package/src/refractor/inspect.mjs

@@ -0,0 +1,171 @@
+import { resolveSpecification } from '@speclynx/apidom-core';
+import { isPlainObject } from 'ramda-adjunct';
+
+/**
+ * OpenAPI 3.1 specification elements.
+ */
+import CallbackElement from "../elements/Callback.mjs";
+import ComponentsElement from "../elements/Components.mjs";
+import ContactElement from "../elements/Contact.mjs";
+import DiscriminatorElement from "../elements/Discriminator.mjs";
+import EncodingElement from "../elements/Encoding.mjs";
+import ExampleElement from "../elements/Example.mjs";
+import ExternalDocumentationElement from "../elements/ExternalDocumentation.mjs";
+import HeaderElement from "../elements/Header.mjs";
+import InfoElement from "../elements/Info.mjs";
+import JsonSchemaDialectElement from "../elements/JsonSchemaDialect.mjs";
+import LicenseElement from "../elements/License.mjs";
+import LinkElement from "../elements/Link.mjs";
+import MediaTypeElement from "../elements/MediaType.mjs";
+import OAuthFlowElement from "../elements/OAuthFlow.mjs";
+import OAuthFlowsElement from "../elements/OAuthFlows.mjs";
+import OpenapiElement from "../elements/Openapi.mjs";
+import OpenApi3_1Element from "../elements/OpenApi3-1.mjs";
+import OperationElement from "../elements/Operation.mjs";
+import ParameterElement from "../elements/Parameter.mjs";
+import PathItemElement from "../elements/PathItem.mjs";
+import PathsElement from "../elements/Paths.mjs";
+import ReferenceElement from "../elements/Reference.mjs";
+import RequestBodyElement from "../elements/RequestBody.mjs";
+import ResponseElement from "../elements/Response.mjs";
+import ResponsesElement from "../elements/Responses.mjs";
+import SchemaElement from "../elements/Schema.mjs";
+import SecurityRequirementElement from "../elements/SecurityRequirement.mjs";
+import SecuritySchemeElement from "../elements/SecurityScheme.mjs";
+import ServerElement from "../elements/Server.mjs";
+import ServerVariableElement from "../elements/ServerVariable.mjs";
+import TagElement from "../elements/Tag.mjs";
+import XmlElement from "../elements/Xml.mjs";
+import specification from "./specification.mjs";
+/**
+ * @public
+ */
+// Resolve specification to dereference $ref pointers
+const resolvedSpec = resolveSpecification(specification);
+
+// Extract fixed fields as list of { name, alias?, $visitor }
+const getFixedFields = fixedFieldsSpec => {
+  return Object.entries(fixedFieldsSpec).map(([name, fieldSpec]) => {
+    if (isPlainObject(fieldSpec)) {
+      return {
+        name,
+        ...fieldSpec
+      };
+    }
+    return {
+      name,
+      $visitor: fieldSpec
+    };
+  });
+};
+
+// OpenAPI 3.1 specification elements
+Object.defineProperty(OpenApi3_1Element, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OpenApi.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(InfoElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Info.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ContactElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Contact.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(LicenseElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.License.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ServerElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Server.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ServerVariableElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.ServerVariable.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ComponentsElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Components.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(PathItemElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.PathItem.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(OperationElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Operation.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ExternalDocumentationElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.ExternalDocumentation.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ParameterElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Parameter.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(RequestBodyElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.RequestBody.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(MediaTypeElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.MediaType.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(EncodingElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Encoding.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ResponsesElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Responses.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ResponseElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Response.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ExampleElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Example.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(LinkElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Link.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(HeaderElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Header.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(TagElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Tag.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(ReferenceElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Reference.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(SchemaElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Schema.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(DiscriminatorElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.Discriminator.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(XmlElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.XML.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(SecuritySchemeElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.SecurityScheme.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(OAuthFlowsElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OAuthFlows.fixedFields),
+  enumerable: true
+});
+Object.defineProperty(OAuthFlowElement, 'fixedFields', {
+  get: () => getFixedFields(resolvedSpec.visitors.document.objects.OAuthFlow.fixedFields),
+  enumerable: true
+});
+export { CallbackElement, ComponentsElement, ContactElement, DiscriminatorElement, EncodingElement, ExampleElement, ExternalDocumentationElement, HeaderElement, InfoElement, JsonSchemaDialectElement, LicenseElement, LinkElement, MediaTypeElement, OAuthFlowElement, OAuthFlowsElement, OpenapiElement, OpenApi3_1Element, OperationElement, ParameterElement, PathItemElement, PathsElement, ReferenceElement, RequestBodyElement, ResponseElement, ResponsesElement, SchemaElement, SecurityRequirementElement, SecuritySchemeElement, ServerElement, ServerVariableElement, TagElement, XmlElement };

package/src/refractor/plugins/normalize-header-examples/NormalizeStorage.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) {
+      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-header-examples/NormalizeStorage.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) {
+      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/plugins/normalize-header-examples/index.cjs

@@ -0,0 +1,109 @@
+"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 _NormalizeStorage = _interopRequireDefault(require("./NormalizeStorage.cjs"));
+/**
+ * Override of Schema.example and Schema.examples field inside the Header Objects.
+ *
+ * Header Object has two fixed fields:
+ *  - `example` of type `Any`
+ *  - `examples` of type `Map[string, Example Object | Reference Object]`
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * The example value SHALL override the example provided by the schema.
+ * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new _NormalizeStorage.default(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      HeaderElement: {
+        leave(path) {
+          const headerElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Header Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Header.schema field present
+          if (typeof headerElement.schema === 'undefined' || !predicates.isSchemaElement(headerElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof headerElement.schema?.example === 'undefined' && typeof headerElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const headerJSONPointer = ancestorLineageToJSONPointer([...ancestors, headerElement]);
+
+          // skip visiting this Header Object if it's already normalized
+          if (storage.includes(headerJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Header.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof headerElement.examples !== 'undefined' && predicates.isObjectElement(headerElement.examples)) {
+            // @ts-ignore
+            const examples = headerElement.examples.map(example => {
+              return _apidomDatamodel.cloneDeep.safe(example.value);
+            });
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', examples);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', examples[0]);
+              storage.append(headerJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof headerElement.example !== 'undefined') {
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', [(0, _apidomDatamodel.cloneDeep)(headerElement.example)]);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', (0, _apidomDatamodel.cloneDeep)(headerElement.example));
+              storage.append(headerJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+var _default = exports.default = plugin;

package/src/refractor/plugins/normalize-header-examples/index.mjs

@@ -0,0 +1,103 @@
+import { cloneDeep } from '@speclynx/apidom-datamodel';
+import NormalizeStorage from "./NormalizeStorage.mjs";
+/**
+ * Override of Schema.example and Schema.examples field inside the Header Objects.
+ *
+ * Header Object has two fixed fields:
+ *  - `example` of type `Any`
+ *  - `examples` of type `Map[string, Example Object | Reference Object]`
+ *
+ * OpenAPI 3.1 specification excerpt that defines the override behavior:
+ *
+ * The example value SHALL override the example provided by the schema.
+ * Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
+ *
+ * NOTE: this plugin is idempotent
+ * @public
+ */
+/**
+ * @public
+ */
+const plugin = ({
+  storageField = 'x-normalized'
+} = {}) => toolbox => {
+  const {
+    predicates,
+    ancestorLineageToJSONPointer
+  } = toolbox;
+  let storage;
+  return {
+    visitor: {
+      OpenApi3_1Element: {
+        enter(path) {
+          const element = path.node;
+          storage = new NormalizeStorage(element, storageField, 'header-examples');
+        },
+        leave() {
+          storage = undefined;
+        }
+      },
+      HeaderElement: {
+        leave(path) {
+          const headerElement = path.node;
+          const ancestors = path.getAncestorNodes().reverse(); // root to parent order
+
+          // skip visiting this Header Object
+          if (ancestors.some(predicates.isComponentsElement)) {
+            return;
+          }
+
+          // no Header.schema field present
+          if (typeof headerElement.schema === 'undefined' || !predicates.isSchemaElement(headerElement.schema)) {
+            return;
+          }
+          // Schema contains no example
+          if (typeof headerElement.schema?.example === 'undefined' && typeof headerElement.schema?.examples === 'undefined') {
+            return;
+          }
+          const headerJSONPointer = ancestorLineageToJSONPointer([...ancestors, headerElement]);
+
+          // skip visiting this Header Object if it's already normalized
+          if (storage.includes(headerJSONPointer)) {
+            return;
+          }
+
+          /**
+           * Header.examples and Schema.examples have preferences over the older
+           * and deprected `example` field.
+           */
+          if (typeof headerElement.examples !== 'undefined' && predicates.isObjectElement(headerElement.examples)) {
+            // @ts-ignore
+            const examples = headerElement.examples.map(example => {
+              return cloneDeep.safe(example.value);
+            });
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', examples);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', examples[0]);
+              storage.append(headerJSONPointer);
+            }
+            return;
+          }
+
+          /**
+           * Handle deprecated `example` field.
+           */
+          if (typeof headerElement.example !== 'undefined') {
+            if (typeof headerElement.schema.examples !== 'undefined') {
+              headerElement.schema.set('examples', [cloneDeep(headerElement.example)]);
+              storage.append(headerJSONPointer);
+            }
+            if (typeof headerElement.schema.example !== 'undefined') {
+              headerElement.schema.set('example', cloneDeep(headerElement.example));
+              storage.append(headerJSONPointer);
+            }
+          }
+        }
+      }
+    }
+  };
+};
+export default plugin;