From 185ed64529f34ace9ad8955fbcbf45241aa9f7b3 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Fri, 19 Aug 2022 14:36:52 -0700
Subject: [PATCH 01/41] feat(apidom-ls): initial oas3.1 path item object
 documentation

---
 .../config/openapi/path-item/documentation.ts | 64 +++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/path-item/documentation.ts

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
new file mode 100644
index 0000000000..2c2b2f334b
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -0,0 +1,64 @@
+const documentation = [
+  {
+    // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
+    target: '$ref',
+    docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).',
+  },
+  {
+    target: 'summary',
+    docs: 'An optional, string summary, intended to apply to all operations in this path.',
+  },
+  {
+    target: 'description',
+    docs: 'An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    target: 'get',
+    // todo: add the table from operation object. recommend build it out first, then copy/paste here
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a GET operation on this path.',
+  },
+  {
+    target: 'put',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PUT operation on this path.',
+  },
+  {
+    target: 'post',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a POST operation on this path.',
+  },
+  {
+    target: 'delete',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a DELETE operation on this path.',
+  },
+  {
+    target: 'options',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a OPTIONS operation on this path.',
+  },
+  {
+    target: 'head',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a HEAD operation on this path.',
+  },
+  {
+    target: 'patch',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PATCH operation on this path.',
+  },
+  {
+    target: 'trace',
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a TRACE operation on this path.',
+  },
+  {
+    target: 'servers',
+    // todo: add the table from server object. recommend build it out first, then copy/paste here
+    docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.',
+  },
+  {
+    target: 'parameters',
+    // todo: add the table from parameter object. recommend build it out first, then copy/paste here
+    docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Objects components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).',
+  },
+  {
+    // todo: add the full list of "Fixed Fields" table
+    docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available',
+  },
+];
+
+export default documentation;

From 9727393c7900ad3306ad3dd646b199253d3b8cc6 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Mon, 22 Aug 2022 14:56:55 -0700
Subject: [PATCH 02/41] feat(apidom-ls): render paths, path-item

Also initial documentation for
* server
* server-variables
---
 .../src/config/openapi/path-item/meta.ts      | 12 +++++++++++
 .../src/config/openapi/paths/documentation.ts |  7 +++++++
 .../src/config/openapi/paths/meta.ts          | 12 +++++++++++
 .../openapi/server-variable/documentation.ts  | 21 +++++++++++++++++++
 .../config/openapi/server/documentation.ts    | 16 ++++++++++++++
 5 files changed, 68 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/path-item/meta.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/paths/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/paths/meta.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/server/documentation.ts

diff --git a/packages/apidom-ls/src/config/openapi/path-item/meta.ts b/packages/apidom-ls/src/config/openapi/path-item/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/path-item/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
new file mode 100644
index 0000000000..3809c258cc
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
@@ -0,0 +1,7 @@
+const documentation = [
+  {
+    docs: 'Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/paths/meta.ts b/packages/apidom-ls/src/config/openapi/paths/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/paths/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
new file mode 100644
index 0000000000..7385c7b04d
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
@@ -0,0 +1,21 @@
+const documentation = [
+  {
+    target: 'enum',
+    docs: 'An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.',
+  },
+  {
+    target: 'default',
+    docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
+  },
+  {
+    target: 'description',
+    docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    // todo: add the full list of "Fixed Fields" table
+    // also: This object MAY be extended with Specification Extensions.
+    docs: '#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
new file mode 100644
index 0000000000..8a25cddca6
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -0,0 +1,16 @@
+const documentation = [
+  {
+    target: 'url',
+    docs: '**REQUIRED.** A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{` brackets `}`.',
+  },
+  {
+    target: 'description',
+    docs: 'An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    target: 'variables',
+    docs: "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
+  },
+];
+
+export default documentation;

From a7d4c82fc548270cfdc6fcf31d09ac60680ccbeb Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Mon, 22 Aug 2022 15:22:53 -0700
Subject: [PATCH 03/41] feat(apidom-ls): render servers, server,
 serverVariables

---
 packages/apidom-ls/src/config/openapi/config.ts      | 10 ++++++++++
 .../src/config/openapi/server-variable/meta.ts       | 12 ++++++++++++
 packages/apidom-ls/src/config/openapi/server/meta.ts | 12 ++++++++++++
 .../src/config/openapi/servers/documentation.ts      |  7 +++++++
 .../apidom-ls/src/config/openapi/servers/meta.ts     | 12 ++++++++++++
 5 files changed, 53 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/server-variable/meta.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/server/meta.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/servers/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/servers/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index cba6fec9ee..d96c80ecdf 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -1,5 +1,10 @@
 import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
+import pathItemMeta from './path-item/meta';
+import pathsMeta from './paths/meta';
+import serversMeta from './servers/meta';
+import serverMeta from './server/meta';
+import serverVariableMeta from './server-variable/meta';
 import schemaMeta from '../common/schema/meta';
 import ApilintCodes from '../codes';
 
@@ -19,4 +24,9 @@ export default {
   info: infoMeta,
   contact: contactMeta,
   schema: schemaMeta,
+  pathItem: pathItemMeta,
+  paths: pathsMeta,
+  servers: serversMeta,
+  server: serverMeta,
+  serverVariables: serverVariableMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/server/meta.ts b/packages/apidom-ls/src/config/openapi/server/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
new file mode 100644
index 0000000000..3ba3029ce3
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
@@ -0,0 +1,7 @@
+const documentation = [
+  {
+    docs: 'An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/servers/meta.ts b/packages/apidom-ls/src/config/openapi/servers/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/servers/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;

From 2a8d5bc2e18d85a4f4a725b523b9118baa26cb38 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 23 Aug 2022 16:09:09 -0700
Subject: [PATCH 04/41] refactor(apidom-ls): wip update oas31 paths
 documentation

---
 packages/apidom-ls/src/config/openapi/paths/documentation.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
index 3809c258cc..9fcb40a59e 100644
--- a/packages/apidom-ls/src/config/openapi/paths/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
@@ -1,6 +1,8 @@
 const documentation = [
   {
-    docs: 'Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).',
+    docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is <em>appended</em> (no relative URL resolution) to the expanded URL from the [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n```\n  /pets/{petId}\n  /pets/mine\n```\n\nThe following paths are considered identical and invalid:\n\n```\n/pets/{petId}\n/pets/{name}\n```\n\nThe following may lead to ambiguous resolution:\n\n```\n/{entity}/me\n/books/{id}\n```',
+    // docsRef:
+    //   '#### [Servers Object](https://www.asyncapi.com/docs/specifications/v2.4.0#serversObject)\n\nThe Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.4.0#serverObject).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n`^[A-Za-z0-9_\\-]+$` | [Server Object](https://www.asyncapi.com/docs/specifications/v2.4.0#serverObject) | The definition of a server this application MAY connect to.\n\n##### Servers Object Example\n\n\n\\\nJSON\n```json\n{\n  "production": {\n    "url": "development.gigantic-server.com",\n    "description": "Development server",\n    "protocol": "kafka",\n    "protocolVersion": "1.0.0"\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\nproduction:\n  url: development.gigantic-server.com\n  description: Development server\n  protocol: kafka\n  protocolVersion: \'1.0.0\'\n```',
   },
 ];
 

From d711b98879ac427e63941e110fd8e6e330279242 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 24 Aug 2022 14:08:08 -0700
Subject: [PATCH 05/41] feat(apidom-ls): oas31 paths documentation

---
 packages/apidom-ls/src/config/openapi/paths/documentation.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
index 9fcb40a59e..923dfc896d 100644
--- a/packages/apidom-ls/src/config/openapi/paths/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
@@ -1,8 +1,6 @@
 const documentation = [
   {
-    docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is <em>appended</em> (no relative URL resolution) to the expanded URL from the [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n```\n  /pets/{petId}\n  /pets/mine\n```\n\nThe following paths are considered identical and invalid:\n\n```\n/pets/{petId}\n/pets/{name}\n```\n\nThe following may lead to ambiguous resolution:\n\n```\n/{entity}/me\n/books/{id}\n```',
-    // docsRef:
-    //   '#### [Servers Object](https://www.asyncapi.com/docs/specifications/v2.4.0#serversObject)\n\nThe Servers Object is a map of [Server Objects](https://www.asyncapi.com/docs/specifications/v2.4.0#serverObject).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n`^[A-Za-z0-9_\\-]+$` | [Server Object](https://www.asyncapi.com/docs/specifications/v2.4.0#serverObject) | The definition of a server this application MAY connect to.\n\n##### Servers Object Example\n\n\n\\\nJSON\n```json\n{\n  "production": {\n    "url": "development.gigantic-server.com",\n    "description": "Development server",\n    "protocol": "kafka",\n    "protocolVersion": "1.0.0"\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\nproduction:\n  url: development.gigantic-server.com\n  description: Development server\n  protocol: kafka\n  protocolVersion: \'1.0.0\'\n```',
+    docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\n\\\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n\n```yaml\n  /pets/{petId}\n  /pets/mine\n```\n\n\nThe following paths are considered identical and invalid:\n\n\n```yaml\n  /pets/{petId}\n  /pets/{name}\n```\n\n\nThe following may lead to ambiguous resolution:\n\n```yaml\n  /{entity}/me\n  /books/{id}\n```\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "/pets": {\n    "get": {\n      "description": "Returns all pets from the system that the user has access to",\n      "responses": {\n        "200": {\n          "description": "A list of pets.",\n          "content": {\n            "application/json": {\n              "schema": {\n                "type": "array",\n                "items": {\n                  "$ref": "#/components/schemas/pet"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\n  /pets:\n    get:\n      description: Returns all pets from the system that the user has access to\n      responses:\n        \'200\':\n          description: A list of pets.\n          content:\n            application\\/ json:\n              schema:\n                type: array\n                items:\n                  $ref: \'#/components/schemas/pet\'\n```\n',
   },
 ];
 

From 7b9603acc82bb3cf375fbe6bf9a48e60d314c49e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 25 Aug 2022 11:27:34 -0700
Subject: [PATCH 06/41] feat(apidom-ls): oas31 path-item documentation

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 2c2b2f334b..4d1d5a4081 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -57,7 +57,7 @@ const documentation = [
   },
   {
     // todo: add the full list of "Fixed Fields" table
-    docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available',
+    docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n',
   },
 ];
 

From 9afff1c106aaa9e4e87240aef11e5948d06880d2 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 25 Aug 2022 13:39:51 -0700
Subject: [PATCH 07/41] refactor(apidom-ls): oas31 docs move to reusable 
 docsPathItemObject

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 4d1d5a4081..ccfcb9509e 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,3 +1,6 @@
+const docsPathItemObject =
+  '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
+
 const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
@@ -56,8 +59,7 @@ const documentation = [
     docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Objects components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).',
   },
   {
-    // todo: add the full list of "Fixed Fields" table
-    docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n',
+    docs: docsPathItemObject,
   },
 ];
 

From 63dddd7384d789194f09839a4442d0edb87f44b3 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 25 Aug 2022 16:25:36 -0700
Subject: [PATCH 08/41] feat(apidom-ls): oas31 operation object documentation
 in path-item

---
 .../config/openapi/path-item/documentation.ts | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index ccfcb9509e..adfd7dbfff 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,6 +1,9 @@
 const docsPathItemObject =
   '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
 
+const docsOperationObject =
+  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Objects components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
+
 const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
@@ -17,36 +20,35 @@ const documentation = [
   },
   {
     target: 'get',
-    // todo: add the table from operation object. recommend build it out first, then copy/paste here
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a GET operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'put',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PUT operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'post',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a POST operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'delete',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a DELETE operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'options',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a OPTIONS operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'head',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a HEAD operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'patch',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PATCH operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'trace',
-    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a TRACE operation on this path.',
+    docs: docsOperationObject,
   },
   {
     target: 'servers',
@@ -56,7 +58,7 @@ const documentation = [
   {
     target: 'parameters',
     // todo: add the table from parameter object. recommend build it out first, then copy/paste here
-    docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Objects components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).',
+    docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).',
   },
   {
     docs: docsPathItemObject,

From 38323bf25a42c98f2232107cf5d0a5bcf785090f Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Fri, 26 Aug 2022 11:22:29 -0700
Subject: [PATCH 09/41] feat(apidom-ls): oas31 servers documentation for
 path-item

---
 .../src/config/openapi/path-item/documentation.ts      | 10 ++++++----
 .../src/config/openapi/paths/documentation.ts          |  2 +-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index adfd7dbfff..954280b05d 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,8 +1,11 @@
 const docsPathItemObject =
-  '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
+  '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
 
 const docsOperationObject =
-  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Objects components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
+  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
+
+const docsServersObject =
+  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
 
 const documentation = [
   {
@@ -52,8 +55,7 @@ const documentation = [
   },
   {
     target: 'servers',
-    // todo: add the table from server object. recommend build it out first, then copy/paste here
-    docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.',
+    docs: docsServersObject,
   },
   {
     target: 'parameters',
diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
index 923dfc896d..8844cb8387 100644
--- a/packages/apidom-ls/src/config/openapi/paths/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
@@ -1,6 +1,6 @@
 const documentation = [
   {
-    docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\n\\\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n\n```yaml\n  /pets/{petId}\n  /pets/mine\n```\n\n\nThe following paths are considered identical and invalid:\n\n\n```yaml\n  /pets/{petId}\n  /pets/{name}\n```\n\n\nThe following may lead to ambiguous resolution:\n\n```yaml\n  /{entity}/me\n  /books/{id}\n```\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "/pets": {\n    "get": {\n      "description": "Returns all pets from the system that the user has access to",\n      "responses": {\n        "200": {\n          "description": "A list of pets.",\n          "content": {\n            "application/json": {\n              "schema": {\n                "type": "array",\n                "items": {\n                  "$ref": "#/components/schemas/pet"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\n  /pets:\n    get:\n      description: Returns all pets from the system that the user has access to\n      responses:\n        \'200\':\n          description: A list of pets.\n          content:\n            application\\/ json:\n              schema:\n                type: array\n                items:\n                  $ref: \'#/components/schemas/pet\'\n```\n',
+    docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object\'s](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\n\\\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n\n```yaml\n  /pets/{petId}\n  /pets/mine\n```\n\n\nThe following paths are considered identical and invalid:\n\n\n```yaml\n  /pets/{petId}\n  /pets/{name}\n```\n\n\nThe following may lead to ambiguous resolution:\n\n```yaml\n  /{entity}/me\n  /books/{id}\n```\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "/pets": {\n    "get": {\n      "description": "Returns all pets from the system that the user has access to",\n      "responses": {\n        "200": {\n          "description": "A list of pets.",\n          "content": {\n            "application/json": {\n              "schema": {\n                "type": "array",\n                "items": {\n                  "$ref": "#/components/schemas/pet"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\n  /pets:\n    get:\n      description: Returns all pets from the system that the user has access to\n      responses:\n        \'200\':\n          description: A list of pets.\n          content:\n            application\\/ json:\n              schema:\n                type: array\n                items:\n                  $ref: \'#/components/schemas/pet\'\n```\n',
   },
 ];
 

From 6668be54dae2d81375327debf4d8ff2ba74931cc Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 30 Aug 2022 14:48:05 -0700
Subject: [PATCH 10/41] feat(apidom-ls): oas31 parameters object documentation
 in path-item

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 954280b05d..c3e8cdfcf5 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -7,6 +7,9 @@ const docsOperationObject =
 const docsServersObject =
   '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
 
+const docsParametersObject =
+  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Style Examples\n\nAssume a parameter name `color` has one of the following values:\n\n`    string -> "blue`\n\n`    array -> ["blue","black","brown"]`\n\n`object -> { "R": 100, "G": 200, "B": 150 }`\n\n\\\nThe following table shows examples of rendering difference for each value:\n\n[`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#styleValues) | `explode` | `empty` | `string` | `array` | `object`\n---|:---:|---:|---:|---:|---:|\nmatrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
+
 const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
@@ -59,8 +62,7 @@ const documentation = [
   },
   {
     target: 'parameters',
-    // todo: add the table from parameter object. recommend build it out first, then copy/paste here
-    docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).',
+    docs: docsParametersObject,
   },
   {
     docs: docsPathItemObject,

From 6b94a2f0bcc9e8966c8d3cdf9fde5a25246f108e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 30 Aug 2022 14:54:02 -0700
Subject: [PATCH 11/41] refactor(apidom-ls): oas31 remove style examples from
 path-item docs

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index c3e8cdfcf5..40e35572d3 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -8,7 +8,7 @@ const docsServersObject =
   '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
 
 const docsParametersObject =
-  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Style Examples\n\nAssume a parameter name `color` has one of the following values:\n\n`    string -> "blue`\n\n`    array -> ["blue","black","brown"]`\n\n`object -> { "R": 100, "G": 200, "B": 150 }`\n\n\\\nThe following table shows examples of rendering difference for each value:\n\n[`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#styleValues) | `explode` | `empty` | `string` | `array` | `object`\n---|:---:|---:|---:|---:|---:|\nmatrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
+  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
 
 const documentation = [
   {

From 5e2b8750a0ddd40871dce131f6beba2967925099 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 30 Aug 2022 16:07:28 -0700
Subject: [PATCH 12/41] feat(apidom-ls): oas31 move some docs from pathItem to
 parent element

* operation
* parameter
* server
---
 .../apidom-ls/src/config/openapi/config.ts    |  5 ++
 .../config/openapi/operation/documentation.ts | 10 ++++
 .../src/config/openapi/operation/meta.ts      | 12 +++++
 .../config/openapi/parameter/documentation.ts | 10 ++++
 .../src/config/openapi/parameter/meta.ts      | 12 +++++
 .../config/openapi/path-item/documentation.ts | 49 -------------------
 .../config/openapi/server/documentation.ts    |  6 +++
 .../config/openapi/servers/documentation.ts   |  5 +-
 packages/apidom-ls/src/config/symbols.ts      |  1 +
 9 files changed, 60 insertions(+), 50 deletions(-)
 create mode 100644 packages/apidom-ls/src/config/openapi/operation/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/operation/meta.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/parameter/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/parameter/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index d96c80ecdf..13a41f24ef 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -1,5 +1,7 @@
 import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
+import operationMeta from './operation/meta';
+import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
 import pathsMeta from './paths/meta';
 import serversMeta from './servers/meta';
@@ -24,6 +26,9 @@ export default {
   info: infoMeta,
   contact: contactMeta,
   schema: schemaMeta,
+  operation: operationMeta,
+  parameter: parameterMeta,
+  parameters: parameterMeta,
   pathItem: pathItemMeta,
   paths: pathsMeta,
   servers: serversMeta,
diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
new file mode 100644
index 0000000000..e667d449b0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -0,0 +1,10 @@
+const docsOperationObject =
+  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
+
+const documentation = [
+  {
+    docs: docsOperationObject,
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/operation/meta.ts b/packages/apidom-ls/src/config/openapi/operation/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/operation/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
new file mode 100644
index 0000000000..66b40b50c2
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -0,0 +1,10 @@
+const docsParametersObject =
+  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
+
+const documentation = [
+  {
+    docs: docsParametersObject,
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/parameter/meta.ts b/packages/apidom-ls/src/config/openapi/parameter/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/parameter/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 40e35572d3..9e0b83e6fb 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,15 +1,6 @@
 const docsPathItemObject =
   '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
 
-const docsOperationObject =
-  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
-
-const docsServersObject =
-  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
-
-const docsParametersObject =
-  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
-
 const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
@@ -24,46 +15,6 @@ const documentation = [
     target: 'description',
     docs: 'An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
-  {
-    target: 'get',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'put',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'post',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'delete',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'options',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'head',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'patch',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'trace',
-    docs: docsOperationObject,
-  },
-  {
-    target: 'servers',
-    docs: docsServersObject,
-  },
-  {
-    target: 'parameters',
-    docs: docsParametersObject,
-  },
   {
     docs: docsPathItemObject,
   },
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index 8a25cddca6..28673859c4 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -1,3 +1,6 @@
+const docsServerObject =
+  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn object representing a Server.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
+
 const documentation = [
   {
     target: 'url',
@@ -11,6 +14,9 @@ const documentation = [
     target: 'variables',
     docs: "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
   },
+  {
+    docs: docsServerObject,
+  },
 ];
 
 export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
index 3ba3029ce3..2f2b9bd2da 100644
--- a/packages/apidom-ls/src/config/openapi/servers/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
@@ -1,6 +1,9 @@
+const docsServersObject =
+  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
+
 const documentation = [
   {
-    docs: 'An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.',
+    docs: docsServersObject,
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/symbols.ts b/packages/apidom-ls/src/config/symbols.ts
index ec4bab42e6..2509de406f 100644
--- a/packages/apidom-ls/src/config/symbols.ts
+++ b/packages/apidom-ls/src/config/symbols.ts
@@ -6,6 +6,7 @@ export default [
   'info',
   'operation',
   'pathItem',
+  'pathItem-parameters',
   'components',
   'components-parameters',
   'components-schemas',

From 03eeb1133b6034c41cc574b37effe35f858f73dd Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 31 Aug 2022 11:24:36 -0700
Subject: [PATCH 13/41] feat(apidom-ls): oas31 docs add targets for parameter
 object

---
 .../config/openapi/parameter/documentation.ts | 49 ++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
index 66b40b50c2..a1865a440f 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -1,7 +1,54 @@
 const docsParametersObject =
-  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding.This property only applies to parameters with an `in` value of `query`.The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
+  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
 
 const documentation = [
+  {
+    target: 'name',
+    docs: '**REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.',
+  },
+  {
+    target: 'in',
+    docs: '**REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.',
+  },
+  {
+    target: 'description',
+    docs: 'A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    target: 'required',
+    docs: 'Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.',
+  },
+  {
+    target: 'deprecated',
+    docs: 'Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.',
+  },
+  {
+    target: 'allowEmptyValue',
+    docs: 'Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.',
+  },
+  {
+    target: 'style',
+    docs: 'Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.',
+  },
+  {
+    target: 'explode',
+    docs: 'When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.',
+  },
+  {
+    target: 'allowReserved',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.",
+  },
+  {
+    // mutually exlusive to `exammples` -> Example Object | Reference Object
+    target: 'example',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.",
+  },
+  {
+    target: 'content',
+    docs: 'A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
+  },
   {
     docs: docsParametersObject,
   },

From 82809b42f9fd5149952ad11d5bf8d45f5916238b Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 31 Aug 2022 11:28:26 -0700
Subject: [PATCH 14/41] feat(apidom-ls): oas31 docs add targets for operation
 object

---
 .../config/openapi/operation/documentation.ts | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index e667d449b0..3ae60a6fea 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -2,6 +2,26 @@ const docsOperationObject =
   '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
 
 const documentation = [
+  {
+    target: 'tags',
+    docs: 'A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.',
+  },
+  {
+    target: 'summary',
+    docs: 'A short summary of what the operation does.',
+  },
+  {
+    target: 'description',
+    docs: 'A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    target: 'operationId',
+    docs: 'Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.',
+  },
+  {
+    target: 'deprecated',
+    docs: 'Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.',
+  },
   {
     docs: docsOperationObject,
   },

From e9db51ce9219362da9f21a60f6e42a9f59a771b2 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 31 Aug 2022 14:16:41 -0700
Subject: [PATCH 15/41] fix(apidom-ls): wip oas31 docs for serverVariables
 object

---
 .../src/config/openapi/server-variable/documentation.ts   | 8 ++++----
 .../apidom-ls/src/config/openapi/server/documentation.ts  | 8 ++++----
 packages/apidom-ls/src/config/symbols.ts                  | 3 +++
 packages/apidom-ls/src/config/tokens.ts                   | 3 +++
 4 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
index 7385c7b04d..22cdf395c6 100644
--- a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
@@ -5,16 +5,16 @@ const documentation = [
   },
   {
     target: 'default',
-    docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
   },
   {
     target: 'description',
     docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
   {
-    // todo: add the full list of "Fixed Fields" table
-    // also: This object MAY be extended with Specification Extensions.
-    docs: '#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n",
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index 28673859c4..d1398541d2 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -10,10 +10,10 @@ const documentation = [
     target: 'description',
     docs: 'An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
-  {
-    target: 'variables',
-    docs: "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
-  },
+  // {
+  //   target: 'variables',
+  //   docs: "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
+  // },
   {
     docs: docsServerObject,
   },
diff --git a/packages/apidom-ls/src/config/symbols.ts b/packages/apidom-ls/src/config/symbols.ts
index 2509de406f..8b76315bf6 100644
--- a/packages/apidom-ls/src/config/symbols.ts
+++ b/packages/apidom-ls/src/config/symbols.ts
@@ -17,6 +17,9 @@ export default [
   'schema',
   'server',
   'servers',
+  'server-variables',
+  // 'servers-variables',
+  // 'serverVariables',
   'title',
   'channelItem',
   'channels',
diff --git a/packages/apidom-ls/src/config/tokens.ts b/packages/apidom-ls/src/config/tokens.ts
index 008f11b7ea..4a52a0f941 100644
--- a/packages/apidom-ls/src/config/tokens.ts
+++ b/packages/apidom-ls/src/config/tokens.ts
@@ -29,6 +29,9 @@ export default [
   'schema',
   'server',
   'servers',
+  'server-variables',
+  // 'servers-variables',
+  // 'serverVariables',
   'title',
   'channelItem',
   'channels',

From 783084b3ff4a453ada03f2199e1b21ed35045d06 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 31 Aug 2022 14:24:43 -0700
Subject: [PATCH 16/41] fix(apidom-ls): oas31 minor changes to pathItem target
 docs

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 9e0b83e6fb..0c26a4b0ba 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -5,11 +5,11 @@ const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
     target: '$ref',
-    docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).',
+    docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).',
   },
   {
     target: 'summary',
-    docs: 'An optional, string summary, intended to apply to all operations in this path.',
+    docs: 'An optional string summary, intended to apply to all operations in this path.',
   },
   {
     target: 'description',

From 22defb10e91f685452da7b326abf4990738135da Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 10:16:06 -0700
Subject: [PATCH 17/41] fix(apidom-ls): fix oas31 pathItem description docs

---
 .../apidom-ls/src/config/openapi/path-item/documentation.ts     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 0c26a4b0ba..19fe9c1945 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -13,7 +13,7 @@ const documentation = [
   },
   {
     target: 'description',
-    docs: 'An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+    docs: 'An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
   {
     docs: docsPathItemObject,

From 5fbf715a6503846eb2352dacc5f7636e29219181 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 10:17:56 -0700
Subject: [PATCH 18/41] fix(apidom-ls): remove extraneous oas31 symbols

---
 packages/apidom-ls/src/config/symbols.ts | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/apidom-ls/src/config/symbols.ts b/packages/apidom-ls/src/config/symbols.ts
index 8b76315bf6..ec4bab42e6 100644
--- a/packages/apidom-ls/src/config/symbols.ts
+++ b/packages/apidom-ls/src/config/symbols.ts
@@ -6,7 +6,6 @@ export default [
   'info',
   'operation',
   'pathItem',
-  'pathItem-parameters',
   'components',
   'components-parameters',
   'components-schemas',
@@ -17,9 +16,6 @@ export default [
   'schema',
   'server',
   'servers',
-  'server-variables',
-  // 'servers-variables',
-  // 'serverVariables',
   'title',
   'channelItem',
   'channels',

From c2a3ead58d0dcb7f4e3d459eb632150de445853e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 10:20:40 -0700
Subject: [PATCH 19/41] feat(apidom-ls): add serverVariable to openapi config

---
 packages/apidom-ls/src/config/openapi/config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 13a41f24ef..0198fb1433 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -34,4 +34,5 @@ export default {
   servers: serversMeta,
   server: serverMeta,
   serverVariables: serverVariableMeta,
+  serverVariable: serverVariableMeta,
 };

From 79d43768eeb065b19118d8748358a9f7e457d9e6 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 11:23:19 -0700
Subject: [PATCH 20/41] fix(apidom-ls): oas31 meta docs for server-variables

---
 packages/apidom-ls/src/config/openapi/config.ts               | 3 +--
 packages/apidom-ls/src/config/openapi/server/documentation.ts | 4 ----
 2 files changed, 1 insertion(+), 6 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 0198fb1433..b5331ea4e2 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -33,6 +33,5 @@ export default {
   paths: pathsMeta,
   servers: serversMeta,
   server: serverMeta,
-  serverVariables: serverVariableMeta,
-  serverVariable: serverVariableMeta,
+  'server-variables': serverVariableMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index d1398541d2..fa95015dd6 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -10,10 +10,6 @@ const documentation = [
     target: 'description',
     docs: 'An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
-  // {
-  //   target: 'variables',
-  //   docs: "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
-  // },
   {
     docs: docsServerObject,
   },

From 0d46a4986815ce433ae87d9ac588932d7587c485 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 14:52:27 -0700
Subject: [PATCH 21/41] refactor(apidom-ls): rename oas31 server-variables

---
 packages/apidom-ls/src/config/openapi/config.ts               | 4 ++--
 .../{server-variable => server-variables}/documentation.ts    | 0
 .../openapi/{server-variable => server-variables}/meta.ts     | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename packages/apidom-ls/src/config/openapi/{server-variable => server-variables}/documentation.ts (100%)
 rename packages/apidom-ls/src/config/openapi/{server-variable => server-variables}/meta.ts (100%)

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index b5331ea4e2..b30415d9e6 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -6,7 +6,7 @@ import pathItemMeta from './path-item/meta';
 import pathsMeta from './paths/meta';
 import serversMeta from './servers/meta';
 import serverMeta from './server/meta';
-import serverVariableMeta from './server-variable/meta';
+import serverVariablesMeta from './server-variables/meta';
 import schemaMeta from '../common/schema/meta';
 import ApilintCodes from '../codes';
 
@@ -33,5 +33,5 @@ export default {
   paths: pathsMeta,
   servers: serversMeta,
   server: serverMeta,
-  'server-variables': serverVariableMeta,
+  'server-variables': serverVariablesMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variables/documentation.ts
similarity index 100%
rename from packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
rename to packages/apidom-ls/src/config/openapi/server-variables/documentation.ts
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts b/packages/apidom-ls/src/config/openapi/server-variables/meta.ts
similarity index 100%
rename from packages/apidom-ls/src/config/openapi/server-variable/meta.ts
rename to packages/apidom-ls/src/config/openapi/server-variables/meta.ts

From 3731dc0e31f396260d56b471ed8d192c8ddf90b7 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 14:53:48 -0700
Subject: [PATCH 22/41] refactor(apidom-ls): minor fixes to oas31 operation
 docs

---
 .../apidom-ls/src/config/openapi/operation/documentation.ts     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index 3ae60a6fea..c2bc711af3 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -1,5 +1,5 @@
 const docsOperationObject =
-  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\requestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\responses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
+  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\nrequestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\nresponses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
 
 const documentation = [
   {

From 0304b0a0c84bc9a61a0b1bb2433911782407074e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 15:57:44 -0700
Subject: [PATCH 23/41] feat(apidom-ls): oas31 docs licenseobject

---
 .../apidom-ls/src/config/openapi/config.ts    |  2 ++
 .../config/openapi/license/documentation.ts   | 19 +++++++++++++++++++
 .../src/config/openapi/license/meta.ts        | 12 ++++++++++++
 3 files changed, 33 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/license/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/license/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index b30415d9e6..81889fcbda 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -1,5 +1,6 @@
 import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
+import licenseMeta from './license/meta';
 import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
@@ -25,6 +26,7 @@ export default {
   },
   info: infoMeta,
   contact: contactMeta,
+  license: licenseMeta,
   schema: schemaMeta,
   operation: operationMeta,
   parameter: parameterMeta,
diff --git a/packages/apidom-ls/src/config/openapi/license/documentation.ts b/packages/apidom-ls/src/config/openapi/license/documentation.ts
new file mode 100644
index 0000000000..e20afec99c
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/license/documentation.ts
@@ -0,0 +1,19 @@
+const documentation = [
+  {
+    target: 'name',
+    docs: '**REQUIRED**. The license name used for the API.',
+  },
+  {
+    target: 'identifier',
+    docs: 'An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.',
+  },
+  {
+    target: 'url',
+    docs: 'A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.',
+  },
+  {
+    docs: '#### [License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#licenseObject)\n\nLicense information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The license name used for the API.\nidentifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.\nurl | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### License Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "Apache 2.0",\n  "identifier": "Apache-2.0"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: Apache 2.0\nidentifier: Apache-2.0\n```',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/license/meta.ts b/packages/apidom-ls/src/config/openapi/license/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/license/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;

From c5a38e85cf5cf13124ce735500a0c4bf3e3979a4 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 1 Sep 2022 16:47:54 -0700
Subject: [PATCH 24/41] feat(apidom-ls): oas31 docs for tags

---
 packages/apidom-ls/src/config/openapi/config.ts  |  2 ++
 .../src/config/openapi/tags/documentation.ts     | 16 ++++++++++++++++
 .../apidom-ls/src/config/openapi/tags/meta.ts    | 12 ++++++++++++
 3 files changed, 30 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/tags/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/tags/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 81889fcbda..445bc24baa 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -1,6 +1,7 @@
 import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
 import licenseMeta from './license/meta';
+import tagsMeta from './tags/meta';
 import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
@@ -36,4 +37,5 @@ export default {
   servers: serversMeta,
   server: serverMeta,
   'server-variables': serverVariablesMeta,
+  tags: tagsMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/tags/documentation.ts b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
new file mode 100644
index 0000000000..ab2a433c26
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
@@ -0,0 +1,16 @@
+const documentation = [
+  { target: 'name', docs: '**REQUIRED**. The name of the tag.' },
+  {
+    target: 'description',
+    docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    target: 'externalDocs',
+    docs: 'Additional external documentation for this tag.',
+  },
+  {
+    docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/tags/meta.ts b/packages/apidom-ls/src/config/openapi/tags/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/tags/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;

From 129507aafe1da9e06f0241df9c3f9c3a15a7e54a Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Fri, 2 Sep 2022 14:27:37 -0700
Subject: [PATCH 25/41] fix(apidom-ls): cumulative oas31 docs feedback changes

---
 .../apidom-ls/src/config/openapi/config.ts    |  6 ++++--
 .../config/openapi/parameter/documentation.ts |  9 ++++++--
 .../config/openapi/path-item/documentation.ts |  8 +++++++
 .../openapi/server-variable/documentation.ts  | 21 +++++++++++++++++++
 .../config/openapi/server-variable/meta.ts    | 12 +++++++++++
 .../config/openapi/server/documentation.ts    |  5 +++++
 .../config/openapi/servers/documentation.ts   |  2 +-
 7 files changed, 58 insertions(+), 5 deletions(-)
 create mode 100644 packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/server-variable/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 445bc24baa..e1ae73357f 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -8,7 +8,8 @@ import pathItemMeta from './path-item/meta';
 import pathsMeta from './paths/meta';
 import serversMeta from './servers/meta';
 import serverMeta from './server/meta';
-import serverVariablesMeta from './server-variables/meta';
+import serverVariableMeta from './server-variable/meta';
+// import serverVariablesMeta from './server-variables/meta';
 import schemaMeta from '../common/schema/meta';
 import ApilintCodes from '../codes';
 
@@ -36,6 +37,7 @@ export default {
   paths: pathsMeta,
   servers: serversMeta,
   server: serverMeta,
-  'server-variables': serverVariablesMeta,
+  // 'server-variables': serverVariablesMeta,
+  serverVariable: serverVariableMeta,
   tags: tagsMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
index a1865a440f..ed04270735 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -4,7 +4,7 @@ const docsParametersObject =
 const documentation = [
   {
     target: 'name',
-    docs: '**REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.',
+    docs: '**REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n\n  * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n\n  * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n\n  * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.',
   },
   {
     target: 'in',
@@ -40,11 +40,16 @@ const documentation = [
     docs: "Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.",
   },
   {
-    // mutually exlusive to `exammples` -> Example Object | Reference Object
+    // mutually exlusive to `examples` -> Example Object | Reference Object
     target: 'example',
     // linter complains about escaping single quote in string, so use double quotes
     docs: "Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.",
   },
+  {
+    target: 'examples',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "#### Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema",
+  },
   {
     target: 'content',
     docs: 'A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 19fe9c1945..244263bada 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -15,6 +15,14 @@ const documentation = [
     target: 'description',
     docs: 'An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
+  {
+    target: 'servers',
+    docs: '#### [[ServerObject](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service all operations in this path.',
+  },
+  {
+    target: 'parameters',
+    docs: "#### [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
+  },
   {
     docs: docsPathItemObject,
   },
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
new file mode 100644
index 0000000000..22cdf395c6
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
@@ -0,0 +1,21 @@
+const documentation = [
+  {
+    target: 'enum',
+    docs: 'An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.',
+  },
+  {
+    target: 'default',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
+  },
+  {
+    target: 'description',
+    docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n",
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index fa95015dd6..3f6befb78c 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -10,6 +10,11 @@ const documentation = [
     target: 'description',
     docs: 'An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
+  {
+    target: 'variables',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "#### Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)]\n\nA map between a variable name and its value. The value is used for substitution in the server's URL template.",
+  },
   {
     docs: docsServerObject,
   },
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
index 2f2b9bd2da..091f07b867 100644
--- a/packages/apidom-ls/src/config/openapi/servers/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
@@ -1,5 +1,5 @@
 const docsServersObject =
-  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn alternative `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
+  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nA `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
 
 const documentation = [
   {

From ec86af3c93604400b5c67d8f8f4d0a5bcde26bfd Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 6 Sep 2022 11:02:20 -0700
Subject: [PATCH 26/41] feat(apidom-ls): oas31 docs for externalDocs

---
 packages/apidom-ls/src/config/openapi/config.ts   |  2 ++
 .../config/openapi/external-docs/documentation.ts | 15 +++++++++++++++
 .../src/config/openapi/external-docs/meta.ts      | 12 ++++++++++++
 3 files changed, 29 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/external-docs/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/external-docs/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index e1ae73357f..e855747c93 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -2,6 +2,7 @@ import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
 import licenseMeta from './license/meta';
 import tagsMeta from './tags/meta';
+import externalDocsMeta from './external-docs/meta';
 import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
@@ -40,4 +41,5 @@ export default {
   // 'server-variables': serverVariablesMeta,
   serverVariable: serverVariableMeta,
   tags: tagsMeta,
+  externalDocumentation: externalDocsMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/external-docs/documentation.ts b/packages/apidom-ls/src/config/openapi/external-docs/documentation.ts
new file mode 100644
index 0000000000..949c94016b
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/external-docs/documentation.ts
@@ -0,0 +1,15 @@
+const documentation = [
+  {
+    target: 'url',
+    docs: '**REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.',
+  },
+  {
+    target: 'description',
+    docs: 'A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#external-documentation-object)\n\nAllows referencing an external resource for extended documentation.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndescription | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nurl | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### External Documentation Object Example\n\n\n\\\nJSON\n```json\n{\n  "description": "Find more info here",\n  "url": "https://example.com"\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: Find more info here\nurl: https://example.com\n```',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/external-docs/meta.ts b/packages/apidom-ls/src/config/openapi/external-docs/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/external-docs/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;

From b17dde4d7938e6928047e789c0ce2ca2d0b79b33 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 6 Sep 2022 11:52:05 -0700
Subject: [PATCH 27/41] feat(apidom-ls): oas31 docs more operation object
 fields

---
 .../config/openapi/operation/documentation.ts | 23 ++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index c2bc711af3..dfb68b1b3b 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -4,7 +4,7 @@ const docsOperationObject =
 const documentation = [
   {
     target: 'tags',
-    docs: 'A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.',
+    docs: '#### [`string`]\n\nA list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.',
   },
   {
     target: 'summary',
@@ -22,6 +22,27 @@ const documentation = [
     target: 'deprecated',
     docs: 'Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.',
   },
+  {
+    target: 'parameters',
+    // linter complains about escaping single quote in string, so use double quotes
+    docs: "[[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
+  },
+  {
+    target: 'requestBody',
+    docs: '[[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nThe request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.',
+  },
+  {
+    target: 'callbacks',
+    docs: 'Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]]\n\nA map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.',
+  },
+  {
+    target: 'security',
+    docs: '#### [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nA declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.',
+  },
+  {
+    target: 'servers',
+    docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.',
+  },
   {
     docs: docsOperationObject,
   },

From 5187be7f5bb98135a4b87b6b2a99eca2d0c3b0b5 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 6 Sep 2022 16:12:52 -0700
Subject: [PATCH 28/41] feat(apidom-ls): oas31 docs for responses object

---
 packages/apidom-ls/src/config/openapi/config.ts      |  2 ++
 .../src/config/openapi/responses/documentation.ts    |  7 +++++++
 .../apidom-ls/src/config/openapi/responses/meta.ts   | 12 ++++++++++++
 3 files changed, 21 insertions(+)
 create mode 100644 packages/apidom-ls/src/config/openapi/responses/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/responses/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index e855747c93..47cdc75843 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -7,6 +7,7 @@ import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
 import pathsMeta from './paths/meta';
+import responsesMeta from './responses/meta';
 import serversMeta from './servers/meta';
 import serverMeta from './server/meta';
 import serverVariableMeta from './server-variable/meta';
@@ -36,6 +37,7 @@ export default {
   parameters: parameterMeta,
   pathItem: pathItemMeta,
   paths: pathsMeta,
+  responses: responsesMeta,
   servers: serversMeta,
   server: serverMeta,
   // 'server-variables': serverVariablesMeta,
diff --git a/packages/apidom-ls/src/config/openapi/responses/documentation.ts b/packages/apidom-ls/src/config/openapi/responses/documentation.ts
new file mode 100644
index 0000000000..0066be9fb3
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/responses/documentation.ts
@@ -0,0 +1,7 @@
+const documentation = [
+  {
+    docs: '#### [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)\n\nA container for the expected responses of an operation. The container maps a HTTP response code to the expected response.\n\n\\\nThe documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.\n\n\\\nThe `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the `Responses Object`.\n\n\\\nThe `Responses Object` MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndefault | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n[HTTP Status Code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | Any [HTTP status code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Responses Object Example\n\n\n\\\nA 200 response for a successful operation and a default response for others (implying an error):\n\n\\\nJSON\n```json\n{\n  "200": {\n    "description": "a pet to be returned",\n    "content": {\n      "application/json": {\n        "schema": {\n          "$ref": "#/components/schemas/Pet"\n        }\n      }\n    }\n  },\n  "default": {\n    "description": "Unexpected error",\n    "content": {\n      "application/json": {\n        "schema": {\n          "$ref": "#/components/schemas/ErrorModel"\n        }\n      }\n    }\n  }\n```\n\n\n\\\nYAML\n```yaml\n\'200\':\n  description: a pet to be returned\n  content:\n    application/json:\n    schema:\n      $ref: \'#/components/schemas/Pet\'\ndefault:\n  description: Unexpected error\n  content:\n    application/json:\n    schema:\n      $ref: \'#/components/schemas/ErrorModel\'\n```\n',
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/responses/meta.ts b/packages/apidom-ls/src/config/openapi/responses/meta.ts
new file mode 100644
index 0000000000..d039cb57e0
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/responses/meta.ts
@@ -0,0 +1,12 @@
+// import lint from './lint';
+// import completion from './completion';
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  // lint,
+  // completion,
+  documentation,
+};
+
+export default meta;

From ab222ec99370fd37a9afddb7f9b6be6ebe8c8d24 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Tue, 6 Sep 2022 16:44:58 -0700
Subject: [PATCH 29/41] refactor(apidom-ls): rename externalDocs to
 externalDocumentation

---
 packages/apidom-ls/src/config/openapi/config.ts               | 4 ++--
 .../documentation.ts                                          | 0
 .../openapi/{external-docs => external-documentation}/meta.ts | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename packages/apidom-ls/src/config/openapi/{external-docs => external-documentation}/documentation.ts (100%)
 rename packages/apidom-ls/src/config/openapi/{external-docs => external-documentation}/meta.ts (100%)

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 47cdc75843..9b36a3d9bd 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -2,7 +2,7 @@ import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
 import licenseMeta from './license/meta';
 import tagsMeta from './tags/meta';
-import externalDocsMeta from './external-docs/meta';
+import externalDocumentationMeta from './external-documentation/meta';
 import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
@@ -43,5 +43,5 @@ export default {
   // 'server-variables': serverVariablesMeta,
   serverVariable: serverVariableMeta,
   tags: tagsMeta,
-  externalDocumentation: externalDocsMeta,
+  externalDocumentation: externalDocumentationMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/external-docs/documentation.ts b/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
similarity index 100%
rename from packages/apidom-ls/src/config/openapi/external-docs/documentation.ts
rename to packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
diff --git a/packages/apidom-ls/src/config/openapi/external-docs/meta.ts b/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts
similarity index 100%
rename from packages/apidom-ls/src/config/openapi/external-docs/meta.ts
rename to packages/apidom-ls/src/config/openapi/external-documentation/meta.ts

From 8192648d6726e51cad7911dcb57d032905b4f699 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:09:54 -0700
Subject: [PATCH 30/41] refactor(apidom-ls): remove unnecessary
 server-variables directory

---
 .../apidom-ls/src/config/openapi/config.ts    |  2 --
 .../openapi/server-variables/documentation.ts | 21 -------------------
 .../config/openapi/server-variables/meta.ts   | 12 -----------
 3 files changed, 35 deletions(-)
 delete mode 100644 packages/apidom-ls/src/config/openapi/server-variables/documentation.ts
 delete mode 100644 packages/apidom-ls/src/config/openapi/server-variables/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 9b36a3d9bd..8c845d1467 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -11,7 +11,6 @@ import responsesMeta from './responses/meta';
 import serversMeta from './servers/meta';
 import serverMeta from './server/meta';
 import serverVariableMeta from './server-variable/meta';
-// import serverVariablesMeta from './server-variables/meta';
 import schemaMeta from '../common/schema/meta';
 import ApilintCodes from '../codes';
 
@@ -40,7 +39,6 @@ export default {
   responses: responsesMeta,
   servers: serversMeta,
   server: serverMeta,
-  // 'server-variables': serverVariablesMeta,
   serverVariable: serverVariableMeta,
   tags: tagsMeta,
   externalDocumentation: externalDocumentationMeta,
diff --git a/packages/apidom-ls/src/config/openapi/server-variables/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variables/documentation.ts
deleted file mode 100644
index 22cdf395c6..0000000000
--- a/packages/apidom-ls/src/config/openapi/server-variables/documentation.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-const documentation = [
-  {
-    target: 'enum',
-    docs: 'An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.',
-  },
-  {
-    target: 'default',
-    // linter complains about escaping single quote in string, so use double quotes
-    docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
-  },
-  {
-    target: 'description',
-    docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
-  },
-  {
-    // linter complains about escaping single quote in string, so use double quotes
-    docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n",
-  },
-];
-
-export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/server-variables/meta.ts b/packages/apidom-ls/src/config/openapi/server-variables/meta.ts
deleted file mode 100644
index d039cb57e0..0000000000
--- a/packages/apidom-ls/src/config/openapi/server-variables/meta.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-// import lint from './lint';
-// import completion from './completion';
-import documentation from './documentation';
-import { FormatMeta } from '../../../apidom-language-types';
-
-const meta: FormatMeta = {
-  // lint,
-  // completion,
-  documentation,
-};
-
-export default meta;

From af4e5b10c7bc7e36c0a982e09b669c29230816de Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:26:49 -0700
Subject: [PATCH 31/41] feat(apidom-ls): oas31 docs add targetSpecs to various
 objects

---
 .../config/openapi/external-documentation/documentation.ts  | 1 +
 .../apidom-ls/src/config/openapi/license/documentation.ts   | 4 ++++
 .../apidom-ls/src/config/openapi/operation/documentation.ts | 6 ++++++
 .../apidom-ls/src/config/openapi/parameter/documentation.ts | 6 ++++++
 .../apidom-ls/src/config/openapi/path-item/documentation.ts | 4 ++++
 .../apidom-ls/src/config/openapi/paths/documentation.ts     | 1 +
 .../apidom-ls/src/config/openapi/responses/documentation.ts | 1 +
 .../src/config/openapi/server-variable/documentation.ts     | 2 ++
 .../apidom-ls/src/config/openapi/server/documentation.ts    | 2 ++
 .../apidom-ls/src/config/openapi/servers/documentation.ts   | 1 +
 packages/apidom-ls/src/config/openapi/tags/documentation.ts | 1 +
 11 files changed, 29 insertions(+)

diff --git a/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts b/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
index 949c94016b..3593093ea4 100644
--- a/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/external-documentation/documentation.ts
@@ -9,6 +9,7 @@ const documentation = [
   },
   {
     docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#external-documentation-object)\n\nAllows referencing an external resource for extended documentation.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndescription | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nurl | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### External Documentation Object Example\n\n\n\\\nJSON\n```json\n{\n  "description": "Find more info here",\n  "url": "https://example.com"\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: Find more info here\nurl: https://example.com\n```',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/license/documentation.ts b/packages/apidom-ls/src/config/openapi/license/documentation.ts
index e20afec99c..cd0eb16c5e 100644
--- a/packages/apidom-ls/src/config/openapi/license/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/license/documentation.ts
@@ -6,13 +6,17 @@ const documentation = [
   {
     target: 'identifier',
     docs: 'An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'url',
     docs: 'A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+    // note: oas30 docs: 'A URL to the license used for the API. MUST be in the format of a URL.
   },
   {
     docs: '#### [License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#licenseObject)\n\nLicense information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The license name used for the API.\nidentifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.\nurl | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### License Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "Apache 2.0",\n  "identifier": "Apache-2.0"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: Apache 2.0\nidentifier: Apache-2.0\n```',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index dfb68b1b3b..be990134ae 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -26,25 +26,31 @@ const documentation = [
     target: 'parameters',
     // linter complains about escaping single quote in string, so use double quotes
     docs: "[[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'requestBody',
     docs: '[[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nThe request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'callbacks',
     docs: 'Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]]\n\nA map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'security',
     docs: '#### [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nA declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'servers',
     docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     docs: docsOperationObject,
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
index ed04270735..81128c539a 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -5,6 +5,7 @@ const documentation = [
   {
     target: 'name',
     docs: '**REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n\n  * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n\n  * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n\n  * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'in',
@@ -17,6 +18,7 @@ const documentation = [
   {
     target: 'required',
     docs: 'Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'deprecated',
@@ -25,6 +27,7 @@ const documentation = [
   {
     target: 'allowEmptyValue',
     docs: 'Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'style',
@@ -33,6 +36,7 @@ const documentation = [
   {
     target: 'explode',
     docs: 'When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'allowReserved',
@@ -49,10 +53,12 @@ const documentation = [
     target: 'examples',
     // linter complains about escaping single quote in string, so use double quotes
     docs: "#### Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'content',
     docs: 'A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     docs: docsParametersObject,
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 244263bada..66fdd1466e 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -6,6 +6,7 @@ const documentation = [
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
     target: '$ref',
     docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'summary',
@@ -18,13 +19,16 @@ const documentation = [
   {
     target: 'servers',
     docs: '#### [[ServerObject](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service all operations in this path.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'parameters',
     docs: "#### [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     docs: docsPathItemObject,
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/paths/documentation.ts b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
index 8844cb8387..3201c27023 100644
--- a/packages/apidom-ls/src/config/openapi/paths/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/paths/documentation.ts
@@ -1,6 +1,7 @@
 const documentation = [
   {
     docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nHolds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering).\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n/{path} | [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [Server Object\'s](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) `url` field in order to construct the full URL. [Path templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) is allowed. When matching URLs, concrete(non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.In case of ambiguous matching, it is up to the tooling to decide which one to use.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Path Templating Matching\n\n\n\\\nAssuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:\n\n\n```yaml\n  /pets/{petId}\n  /pets/mine\n```\n\n\nThe following paths are considered identical and invalid:\n\n\n```yaml\n  /pets/{petId}\n  /pets/{name}\n```\n\n\nThe following may lead to ambiguous resolution:\n\n```yaml\n  /{entity}/me\n  /books/{id}\n```\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "/pets": {\n    "get": {\n      "description": "Returns all pets from the system that the user has access to",\n      "responses": {\n        "200": {\n          "description": "A list of pets.",\n          "content": {\n            "application/json": {\n              "schema": {\n                "type": "array",\n                "items": {\n                  "$ref": "#/components/schemas/pet"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\n  /pets:\n    get:\n      description: Returns all pets from the system that the user has access to\n      responses:\n        \'200\':\n          description: A list of pets.\n          content:\n            application\\/ json:\n              schema:\n                type: array\n                items:\n                  $ref: \'#/components/schemas/pet\'\n```\n',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/responses/documentation.ts b/packages/apidom-ls/src/config/openapi/responses/documentation.ts
index 0066be9fb3..fd8667a272 100644
--- a/packages/apidom-ls/src/config/openapi/responses/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/responses/documentation.ts
@@ -1,6 +1,7 @@
 const documentation = [
   {
     docs: '#### [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)\n\nA container for the expected responses of an operation. The container maps a HTTP response code to the expected response.\n\n\\\nThe documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors.\n\n\\\nThe `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the `Responses Object`.\n\n\\\nThe `Responses Object` MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndefault | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.\n\n##### Patterned Fields\n\nField Pattern | Type | Description\n---|:---:|---\n[HTTP Status Code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) | [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responseObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) | Any [HTTP status code](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Responses Object Example\n\n\n\\\nA 200 response for a successful operation and a default response for others (implying an error):\n\n\\\nJSON\n```json\n{\n  "200": {\n    "description": "a pet to be returned",\n    "content": {\n      "application/json": {\n        "schema": {\n          "$ref": "#/components/schemas/Pet"\n        }\n      }\n    }\n  },\n  "default": {\n    "description": "Unexpected error",\n    "content": {\n      "application/json": {\n        "schema": {\n          "$ref": "#/components/schemas/ErrorModel"\n        }\n      }\n    }\n  }\n```\n\n\n\\\nYAML\n```yaml\n\'200\':\n  description: a pet to be returned\n  content:\n    application/json:\n    schema:\n      $ref: \'#/components/schemas/Pet\'\ndefault:\n  description: Unexpected error\n  content:\n    application/json:\n    schema:\n      $ref: \'#/components/schemas/ErrorModel\'\n```\n',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
index 22cdf395c6..1bf310e224 100644
--- a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
@@ -7,6 +7,7 @@ const documentation = [
     target: 'default',
     // linter complains about escaping single quote in string, so use double quotes
     docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'description',
@@ -15,6 +16,7 @@ const documentation = [
   {
     // linter complains about escaping single quote in string, so use double quotes
     docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index 3f6befb78c..98ec6edafa 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -14,9 +14,11 @@ const documentation = [
     target: 'variables',
     // linter complains about escaping single quote in string, so use double quotes
     docs: "#### Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)]\n\nA map between a variable name and its value. The value is used for substitution in the server's URL template.",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     docs: docsServerObject,
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
index 091f07b867..100c5bb724 100644
--- a/packages/apidom-ls/src/config/openapi/servers/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
@@ -4,6 +4,7 @@ const docsServersObject =
 const documentation = [
   {
     docs: docsServersObject,
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/tags/documentation.ts b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
index ab2a433c26..7a91a56587 100644
--- a/packages/apidom-ls/src/config/openapi/tags/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
@@ -10,6 +10,7 @@ const documentation = [
   },
   {
     docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
 

From 696f627b6103706a7c857d2ffb77c1c51bd41a8b Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:31:22 -0700
Subject: [PATCH 32/41] refactor(apidom-ls): oas31 docs remove placeholder
 imports

---
 .../src/config/openapi/external-documentation/meta.ts         | 4 ----
 packages/apidom-ls/src/config/openapi/license/meta.ts         | 4 ----
 packages/apidom-ls/src/config/openapi/operation/meta.ts       | 4 ----
 packages/apidom-ls/src/config/openapi/parameter/meta.ts       | 4 ----
 packages/apidom-ls/src/config/openapi/path-item/meta.ts       | 4 ----
 packages/apidom-ls/src/config/openapi/paths/meta.ts           | 4 ----
 packages/apidom-ls/src/config/openapi/responses/meta.ts       | 4 ----
 packages/apidom-ls/src/config/openapi/server-variable/meta.ts | 4 ----
 packages/apidom-ls/src/config/openapi/server/meta.ts          | 4 ----
 packages/apidom-ls/src/config/openapi/servers/meta.ts         | 4 ----
 packages/apidom-ls/src/config/openapi/tags/meta.ts            | 4 ----
 11 files changed, 44 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts b/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/external-documentation/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/license/meta.ts b/packages/apidom-ls/src/config/openapi/license/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/license/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/license/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/operation/meta.ts b/packages/apidom-ls/src/config/openapi/operation/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/operation/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/parameter/meta.ts b/packages/apidom-ls/src/config/openapi/parameter/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/path-item/meta.ts b/packages/apidom-ls/src/config/openapi/path-item/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/paths/meta.ts b/packages/apidom-ls/src/config/openapi/paths/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/paths/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/paths/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/responses/meta.ts b/packages/apidom-ls/src/config/openapi/responses/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/responses/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/responses/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/server-variable/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/server/meta.ts b/packages/apidom-ls/src/config/openapi/server/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/server/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/server/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/servers/meta.ts b/packages/apidom-ls/src/config/openapi/servers/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/servers/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/servers/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 
diff --git a/packages/apidom-ls/src/config/openapi/tags/meta.ts b/packages/apidom-ls/src/config/openapi/tags/meta.ts
index d039cb57e0..33a6f79694 100644
--- a/packages/apidom-ls/src/config/openapi/tags/meta.ts
+++ b/packages/apidom-ls/src/config/openapi/tags/meta.ts
@@ -1,11 +1,7 @@
-// import lint from './lint';
-// import completion from './completion';
 import documentation from './documentation';
 import { FormatMeta } from '../../../apidom-language-types';
 
 const meta: FormatMeta = {
-  // lint,
-  // completion,
   documentation,
 };
 

From bbd20e0c1b6881c75ea282c78c367bebaee3daa9 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:37:02 -0700
Subject: [PATCH 33/41] chore(apidom-ls): oas31 docs remove linting comments

---
 .../apidom-ls/src/config/openapi/operation/documentation.ts   | 1 -
 .../apidom-ls/src/config/openapi/parameter/documentation.ts   | 4 ----
 .../src/config/openapi/server-variable/documentation.ts       | 2 --
 packages/apidom-ls/src/config/openapi/server/documentation.ts | 1 -
 4 files changed, 8 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index be990134ae..93e5f00f4a 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -24,7 +24,6 @@ const documentation = [
   },
   {
     target: 'parameters',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "[[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
index 81128c539a..439707c651 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -40,18 +40,14 @@ const documentation = [
   },
   {
     target: 'allowReserved',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.",
   },
   {
-    // mutually exlusive to `examples` -> Example Object | Reference Object
     target: 'example',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.",
   },
   {
     target: 'examples',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "#### Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
diff --git a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
index 1bf310e224..02a869723d 100644
--- a/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server-variable/documentation.ts
@@ -5,7 +5,6 @@ const documentation = [
   },
   {
     target: 'default',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "**REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
@@ -14,7 +13,6 @@ const documentation = [
     docs: 'An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
   {
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "#### [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)\n\nAn object representing a Server Variable for server URL template substitution.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nenum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.\ndefault | `string` | **REQUIRED.** The default value to use for substitution, which SHALL be sent if an alternate value is *not* supplied. Note this behavior is different than the [Schema Object's](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) treatment of default values, because in those cases parameter values are optional.If the [`enum`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableEnum) is defined, the value MUST exist in the enum's values.\ndescription | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index 98ec6edafa..7bde8a3406 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -12,7 +12,6 @@ const documentation = [
   },
   {
     target: 'variables',
-    // linter complains about escaping single quote in string, so use double quotes
     docs: "#### Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)]\n\nA map between a variable name and its value. The value is used for substitution in the server's URL template.",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },

From 2810010127bb29739762f74bbb68b0e3c1124c13 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:50:54 -0700
Subject: [PATCH 34/41] refactor(apidom-ls): oas31 docs parameter content field

---
 .../src/config/openapi/parameter/documentation.ts          | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
index 439707c651..b76fba9ffe 100644
--- a/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/parameter/documentation.ts
@@ -1,6 +1,3 @@
-const docsParametersObject =
-  '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n';
-
 const documentation = [
   {
     target: 'name',
@@ -53,11 +50,11 @@ const documentation = [
   },
   {
     target: 'content',
-    docs: 'A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
+    docs: 'Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)]\n\nA map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
-    docs: docsParametersObject,
+    docs: '#### [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject)\n\nDescribes a single operation parameter.\n\nA unique parameter is defined by a combination of a [name](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn).\n\n##### Parameter Locations\n\nThere are four possible parameter locations specified by the `in` field:\n\n* path - Used together with [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating), where the parameter value is actually part of the operations URL. This does not include the host or base path of the API. For example, in `/items/{ itemId}`, the path parameter is `itemId`.\n* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.\n* cookie - Used to pass a specific cookie value to the API.\n\n##### Fixed Fields  \n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsPath) field in the [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject). See [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathTemplating) for further information.\n&nbsp; | &nbsp; | * If [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.\n&nbsp; | &nbsp; | * For all other cases, the `name` corresponds to the parameter name used by the [`in`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) property.\nin | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`.\ndescription | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nrequired | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.\ndeprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.\nallowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.\n\n\\\nThe rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.\n\nField Name | Type | Description\n---|:---:|---\nstyle | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.\nexplode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.\nallowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&\'()*+,;=` to be included without percent - encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.\nschema | [Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) | The schema defining the type used for the parameter.\nexample | Any | Example of the parameter\'s potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL *override* the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.\nexamples | Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | Examples of the parameter\'s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL *override* the example provided by the schema.\n\n\\\nFor more complex scenarios, the [`content`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter.\n\nField Name | Type | Description\n---|:---:|---\ncontent | Map[`string`, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.\n\n##### Style Values\n\nIn order to support common ways of serializing simple parameters, a set of `style` values are defined.\n\n`style` | [`type`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#dataTypes) | `in` | Comments\n---|:---:|---:|---\nmatrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nlabel | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)\nform | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.\nsimple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.\nspaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.\npipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.\ndeepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.\n\n##### Examples\n\nExternal reference link to [Style Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#style-examples)\n\nExternal reference link to [Parameter Object Examples](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object-examples)\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n',
   },
 ];
 

From 5ed1bb07b33a53d7c3c4730b5d017e1c425dd924 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 10:56:10 -0700
Subject: [PATCH 35/41] refactor(apidom-ls): oas31 docs directly set value as
 string

---
 .../apidom-ls/src/config/openapi/operation/documentation.ts  | 5 +----
 .../apidom-ls/src/config/openapi/path-item/documentation.ts  | 5 +----
 .../apidom-ls/src/config/openapi/server/documentation.ts     | 5 +----
 .../apidom-ls/src/config/openapi/servers/documentation.ts    | 5 +----
 4 files changed, 4 insertions(+), 16 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index 93e5f00f4a..55d2a56ca2 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -1,6 +1,3 @@
-const docsOperationObject =
-  '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\nrequestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\nresponses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n';
-
 const documentation = [
   {
     target: 'tags',
@@ -48,7 +45,7 @@ const documentation = [
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
-    docs: docsOperationObject,
+    docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\nrequestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\nresponses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 66fdd1466e..690249faf5 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,6 +1,3 @@
-const docsPathItemObject =
-  '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n';
-
 const documentation = [
   {
     // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
@@ -27,7 +24,7 @@ const documentation = [
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
-    docs: docsPathItemObject,
+    docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
diff --git a/packages/apidom-ls/src/config/openapi/server/documentation.ts b/packages/apidom-ls/src/config/openapi/server/documentation.ts
index 7bde8a3406..684663e37f 100644
--- a/packages/apidom-ls/src/config/openapi/server/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/server/documentation.ts
@@ -1,6 +1,3 @@
-const docsServerObject =
-  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn object representing a Server.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
-
 const documentation = [
   {
     target: 'url',
@@ -16,7 +13,7 @@ const documentation = [
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
-    docs: docsServerObject,
+    docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nAn object representing a Server.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
index 100c5bb724..47b4b7ea17 100644
--- a/packages/apidom-ls/src/config/openapi/servers/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/servers/documentation.ts
@@ -1,9 +1,6 @@
-const docsServersObject =
-  '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nA `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n';
-
 const documentation = [
   {
-    docs: docsServersObject,
+    docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nA `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
 ];

From 82ec71caa07ae36250a76f3da49bc604dacb8843 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 11:27:51 -0700
Subject: [PATCH 36/41] refactor(apidom-ls): oas31 docs remove unneed
 tags.externalDocs

---
 packages/apidom-ls/src/config/openapi/tags/documentation.ts | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/tags/documentation.ts b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
index 7a91a56587..6e3b2fe066 100644
--- a/packages/apidom-ls/src/config/openapi/tags/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
@@ -4,10 +4,6 @@ const documentation = [
     target: 'description',
     docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
-  {
-    target: 'externalDocs',
-    docs: 'Additional external documentation for this tag.',
-  },
   {
     docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],

From e70fdb59232021beae2c503deecc3f85d63e796e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 11:34:05 -0700
Subject: [PATCH 37/41] chore(apidom-ls): oas31 docs remove comments about
 oas30

---
 packages/apidom-ls/src/config/openapi/license/documentation.ts   | 1 -
 packages/apidom-ls/src/config/openapi/path-item/documentation.ts | 1 -
 2 files changed, 2 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/license/documentation.ts b/packages/apidom-ls/src/config/openapi/license/documentation.ts
index cd0eb16c5e..6e743eaa19 100644
--- a/packages/apidom-ls/src/config/openapi/license/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/license/documentation.ts
@@ -12,7 +12,6 @@ const documentation = [
     target: 'url',
     docs: 'A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
-    // note: oas30 docs: 'A URL to the license used for the API. MUST be in the format of a URL.
   },
   {
     docs: '#### [License Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#licenseObject)\n\nLicense information for the exposed API.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The license name used for the API.\nidentifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.\nurl | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.\n\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### License Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "Apache 2.0",\n  "identifier": "Apache-2.0"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: Apache 2.0\nidentifier: Apache-2.0\n```',
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index 690249faf5..f736ce990b 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -1,6 +1,5 @@
 const documentation = [
   {
-    // OAS 3.1 adds the last sentence vs OAS3.0.3, re: "rules for resolving"
     target: '$ref',
     docs: 'Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],

From 5bdef78a6ffd17666918f8b0ff4b020b896bd5e3 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 13:11:09 -0700
Subject: [PATCH 38/41] feat(apidom-ls): oas31 docs tag object

---
 packages/apidom-ls/src/config/openapi/config.ts     |  2 ++
 .../src/config/openapi/tag/documentation.ts         | 13 +++++++++++++
 packages/apidom-ls/src/config/openapi/tag/meta.ts   |  8 ++++++++
 .../src/config/openapi/tags/documentation.ts        |  8 +-------
 4 files changed, 24 insertions(+), 7 deletions(-)
 create mode 100644 packages/apidom-ls/src/config/openapi/tag/documentation.ts
 create mode 100644 packages/apidom-ls/src/config/openapi/tag/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 8c845d1467..8dd64da5b7 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -1,6 +1,7 @@
 import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
 import licenseMeta from './license/meta';
+import tagMeta from './tag/meta';
 import tagsMeta from './tags/meta';
 import externalDocumentationMeta from './external-documentation/meta';
 import operationMeta from './operation/meta';
@@ -41,5 +42,6 @@ export default {
   server: serverMeta,
   serverVariable: serverVariableMeta,
   tags: tagsMeta,
+  tag: tagMeta,
   externalDocumentation: externalDocumentationMeta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/tag/documentation.ts b/packages/apidom-ls/src/config/openapi/tag/documentation.ts
new file mode 100644
index 0000000000..6e3b2fe066
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/tag/documentation.ts
@@ -0,0 +1,13 @@
+const documentation = [
+  { target: 'name', docs: '**REQUIRED**. The name of the tag.' },
+  {
+    target: 'description',
+    docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+  },
+  {
+    docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
+];
+
+export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/tag/meta.ts b/packages/apidom-ls/src/config/openapi/tag/meta.ts
new file mode 100644
index 0000000000..33a6f79694
--- /dev/null
+++ b/packages/apidom-ls/src/config/openapi/tag/meta.ts
@@ -0,0 +1,8 @@
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  documentation,
+};
+
+export default meta;
diff --git a/packages/apidom-ls/src/config/openapi/tags/documentation.ts b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
index 6e3b2fe066..18ecd94381 100644
--- a/packages/apidom-ls/src/config/openapi/tags/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
@@ -1,12 +1,6 @@
 const documentation = [
-  { target: 'name', docs: '**REQUIRED**. The name of the tag.' },
   {
-    target: 'description',
-    docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
-  },
-  {
-    docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
-    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+    docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.\n",
   },
 ];
 

From ae230410467a6b406f186a413868aab4dc811083 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Wed, 7 Sep 2022 13:38:17 -0700
Subject: [PATCH 39/41] feat(apidom-ls): oas31 docs openapi3_1 with tags and
 servers

---
 packages/apidom-ls/src/config/openapi/config.ts    |  6 ++----
 .../{servers => openapi3_1}/documentation.ts       | 14 +++++++++++++-
 .../config/openapi/{servers => openapi3_1}/meta.ts |  0
 .../src/config/openapi/tags/documentation.ts       |  7 -------
 packages/apidom-ls/src/config/openapi/tags/meta.ts |  8 --------
 5 files changed, 15 insertions(+), 20 deletions(-)
 rename packages/apidom-ls/src/config/openapi/{servers => openapi3_1}/documentation.ts (82%)
 rename packages/apidom-ls/src/config/openapi/{servers => openapi3_1}/meta.ts (100%)
 delete mode 100644 packages/apidom-ls/src/config/openapi/tags/documentation.ts
 delete mode 100644 packages/apidom-ls/src/config/openapi/tags/meta.ts

diff --git a/packages/apidom-ls/src/config/openapi/config.ts b/packages/apidom-ls/src/config/openapi/config.ts
index 8dd64da5b7..69ae485abf 100644
--- a/packages/apidom-ls/src/config/openapi/config.ts
+++ b/packages/apidom-ls/src/config/openapi/config.ts
@@ -2,16 +2,15 @@ import infoMeta from './info/meta';
 import contactMeta from './contact/meta';
 import licenseMeta from './license/meta';
 import tagMeta from './tag/meta';
-import tagsMeta from './tags/meta';
 import externalDocumentationMeta from './external-documentation/meta';
 import operationMeta from './operation/meta';
 import parameterMeta from './parameter/meta';
 import pathItemMeta from './path-item/meta';
 import pathsMeta from './paths/meta';
 import responsesMeta from './responses/meta';
-import serversMeta from './servers/meta';
 import serverMeta from './server/meta';
 import serverVariableMeta from './server-variable/meta';
+import openapi3_1Meta from './openapi3_1/meta';
 import schemaMeta from '../common/schema/meta';
 import ApilintCodes from '../codes';
 
@@ -38,10 +37,9 @@ export default {
   pathItem: pathItemMeta,
   paths: pathsMeta,
   responses: responsesMeta,
-  servers: serversMeta,
   server: serverMeta,
   serverVariable: serverVariableMeta,
-  tags: tagsMeta,
   tag: tagMeta,
   externalDocumentation: externalDocumentationMeta,
+  openApi3_1: openapi3_1Meta,
 };
diff --git a/packages/apidom-ls/src/config/openapi/servers/documentation.ts b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
similarity index 82%
rename from packages/apidom-ls/src/config/openapi/servers/documentation.ts
rename to packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
index 47b4b7ea17..0f19d1f206 100644
--- a/packages/apidom-ls/src/config/openapi/servers/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
@@ -1,7 +1,19 @@
 const documentation = [
   {
+    target: 'servers',
     docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nA `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n',
-    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.1.0' },
+      { namespace: 'openapi', version: '3.0.0' },
+    ],
+  },
+  {
+    target: 'tags',
+    docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.\n",
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.1.0' },
+      { namespace: 'openapi', version: '3.0.0' },
+    ],
   },
 ];
 
diff --git a/packages/apidom-ls/src/config/openapi/servers/meta.ts b/packages/apidom-ls/src/config/openapi/openapi3_1/meta.ts
similarity index 100%
rename from packages/apidom-ls/src/config/openapi/servers/meta.ts
rename to packages/apidom-ls/src/config/openapi/openapi3_1/meta.ts
diff --git a/packages/apidom-ls/src/config/openapi/tags/documentation.ts b/packages/apidom-ls/src/config/openapi/tags/documentation.ts
deleted file mode 100644
index 18ecd94381..0000000000
--- a/packages/apidom-ls/src/config/openapi/tags/documentation.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-const documentation = [
-  {
-    docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.\n",
-  },
-];
-
-export default documentation;
diff --git a/packages/apidom-ls/src/config/openapi/tags/meta.ts b/packages/apidom-ls/src/config/openapi/tags/meta.ts
deleted file mode 100644
index 33a6f79694..0000000000
--- a/packages/apidom-ls/src/config/openapi/tags/meta.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import documentation from './documentation';
-import { FormatMeta } from '../../../apidom-language-types';
-
-const meta: FormatMeta = {
-  documentation,
-};
-
-export default meta;

From 1d9bb8541e67ef961301f6a1f0cd77f617b7dea2 Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 8 Sep 2022 09:43:56 -0700
Subject: [PATCH 40/41] chore(apidom-ls): oas31 docs dev comments for disabled
 targets

---
 .../config/openapi/operation/documentation.ts |  9 ++++
 .../config/openapi/path-item/documentation.ts | 44 +++++++++++++++++++
 .../src/config/openapi/tag/documentation.ts   |  9 ++++
 3 files changed, 62 insertions(+)

diff --git a/packages/apidom-ls/src/config/openapi/operation/documentation.ts b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
index 55d2a56ca2..59d03a2bef 100644
--- a/packages/apidom-ls/src/config/openapi/operation/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/operation/documentation.ts
@@ -44,6 +44,15 @@ const documentation = [
     docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
+  /**
+   * The following Fixed Field is provided as reference, but is more
+   * comprehensively described by parent External Documentation Object meta documentation
+   */
+  // {
+  //   target: 'externalDocs',
+  //   docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation for this operation.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
   {
     docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nDescribes a single API operation on a path.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.\nsummary | `string` | A short summary of what the operation does.\ndescription | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\texternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this operation.\noperationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.\nparameters | [[Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemParameters), 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\nrequestBody | [[Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#requestBodyObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.\nresponses | [Responses Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responsesObject) | The list of possible responses as they are returned from executing this operation.\ncallbacks | Map[`string`, [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.\ndeprecated |`boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.\nsecurity | [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasSecurity). To remove a top-level security declaration, an empty array can be used.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative server array to service this operation. If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Operation Object Example\n\n\n\\\nJSON\n```json\n{\n  "tags": [\n    "pet"\n  ],\n  "summary": "Updates a pet in the store with form data",\n  "operationId": "updatePetWithForm",\n  "parameters": [\n    {\n      "name": "petId",\n      "in": "path",\n      "description": "ID of pet that needs to be updated",\n      "required": true,\n      "schema": {\n        "type": "string"\n      }\n    }\n  ],\n  "requestBody": {\n    "content": {\n      "application/x-www-form-urlencoded": {\n        "schema": {\n          "type": "object",\n          "properties": {\n            "name": {\n              "description": "Updated name of the pet",\n              "type": "string"\n            },\n            "status": {\n              "description": "Updated status of the pet",\n              "type": "string"\n            }\n          },\n          "required": ["status"]\n        }\n      }\n    }\n  },\n  "responses": {\n    "200": {\n      "description": "Pet updated.",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    },\n    "405": {\n      "description": "Method Not Allowed",\n        "content": {\n        "application/json": {},\n        "application/xml": {}\n      }\n    }\n  },\n  "security": [\n    {\n      "petstore_auth": [\n        "write:pets",\n        "read:pets"\n      ]\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\ntags:\n- pet\nsummary: Updates a pet in the store with form data\noperationId: updatePetWithForm\nparameters:\n- name: petId\n  in: path\n  description: ID of pet that needs to be updated\n  required: true\n  schema:\n    type: string\nrequestBody:\n  content:\n    \'application/x-www-form-urlencoded\':\n      schema:\n        type: object\n        properties:\n          name:\n            description: Updated name of the pet\n            type: string\n          status:\n            description: Updated status of the pet\n            type: string\n        required:\n          - status\nresponses:\n  \'200\':\n    description: Pet updated.\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\n  \'405\':\n    description: Method Not Allowed\n    content:\n      \'application/json\': {}\n      \'application/xml\': {}\nsecurity:\n- petstore_auth:\n  - write: pets\n  - read:pets\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
diff --git a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
index f736ce990b..2fc85c1d48 100644
--- a/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/path-item/documentation.ts
@@ -22,6 +22,50 @@ const documentation = [
     docs: "#### [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\nA 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).",
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
+  /**
+   * The following Fixed Fields are provided as reference, but are more
+   * comprehensively described by parent Operation Object meta documentation
+   */
+  // {
+  //   target: 'get',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a GET operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'put',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PUT operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'post',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a POST operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'delete',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a DELETE operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'options',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a OPTIONS operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'head',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a HEAD operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'patch',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a PATCH operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'trace',
+  //   docs: '#### [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject)\n\nA definition of a TRACE operation on this path.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
   {
     docs: '#### [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject)\n\nDescribes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\n$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#relativeReferencesURI).\nsummary | `string` | An optional, string summary, intended to apply to all operations in this path.\ndescription | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\tget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\nput | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PUT operation on this path.\npost | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a POST operation on this path.\ndelete | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a DELETE operation on this path.\noptions | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a OPTIONS operation on this path.\nhead | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a HEAD operation on this path.\npatch | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a PATCH operation on this path.\nget | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a GET operation on this path.\ntrace | [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) | A definition of a TRACE operation on this path.\nservers | [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)] | An alternative `server` array to service all operations in this path.\nparamenters | [[Parameter](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)] | 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](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterName) and [location](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterIn). The list can use the [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject) to link to parameters that are defined at the [OpenAPI Object\'s components/parameters](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsParameters).\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Paths Object Example\n\n\n\\\nJSON\n```json\n{\n  "get": {\n    "description": "Returns pets based on ID",\n    "summary": "Find pets by ID",\n    "operationId": "getPetsById",\n    "responses": {\n      "200": {\n        "description": "pet response",\n        "content": {\n          "*/*": {\n            "schema": {\n              "type": "array",\n              "items": {\n                "$ref": "#/components/schemas/Pet"\n              }\n            }\n          }\n        }\n      },\n      "default": {\n        "description": "error payload",\n        "content": {\n          "text/html": {\n            "schema": {\n              "$ref": "#/components/schemas/ErrorModel"\n            }\n          }\n        }\n      }\n    }\n  },\n  "parameters": [\n    {\n      "name": "id",\n      "in": "path",\n      "description": "ID of pet to use",\n      "required": true,\n      "schema": {\n        "type": "array",\n        "items": {\n          "type": "string"\n        }\n      },\n      "style": "simple"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nget:\n  description: Returns pets based on ID\n  summary: Find pets by ID\n  operationId: getPetsById\n  responses:\n    \'200\':\n      description: pet response\n      content:\n        \'*/*\' :\n          schema:\n          type: array\n          items:\n            $ref: \'#/components/schemas/Pet\'\n    default:\n      description: error payload\n      content:\n        \'text/html\':\n        schema:\n          $ref: \'#/components/schemas/ErrorModel\'\nparameters:\n- name: id\n  in: path\n  description: ID of pet to use\n  required: true\n  schema:\n    type: array\n    items:\n      type: string\n  style: simple\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
diff --git a/packages/apidom-ls/src/config/openapi/tag/documentation.ts b/packages/apidom-ls/src/config/openapi/tag/documentation.ts
index 6e3b2fe066..cd47b66c99 100644
--- a/packages/apidom-ls/src/config/openapi/tag/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/tag/documentation.ts
@@ -4,6 +4,15 @@ const documentation = [
     target: 'description',
     docs: 'A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
   },
+  /**
+   * The following Fixed Field is provided as reference, but is more
+   * comprehensively described by parent External Documentation Object meta documentation
+   */
+  // {
+  //   target: 'externalDocs',
+  //   docs: '#### [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation for this operation.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
   {
     docs: '#### [Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tag-object)\n\nAdds metadata to a single tag that is used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `string` | **REQUIRED**. The name of the tag.\ndescription | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nexternalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject) | Additional external documentation for this tag.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Tag Object Example\n\n\n\\\nJSON\n```json\n{\n  "name": "pet",\n  "description": "Pets operations"\n}\n```\n\n\n\\\nYAML\n```yaml\nname: pet\ndescription: Pets operations\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],

From dc3eb1dad340af86bfe61d6c4b91c4e33bb5a67e Mon Sep 17 00:00:00 2001
From: Timothy Lai <timothy.lai@smartbear.com>
Date: Thu, 8 Sep 2022 10:32:11 -0700
Subject: [PATCH 41/41] feat(apidom-ls): oas31 docs complete openapi3_1 fields

---
 .../openapi/openapi3_1/documentation.ts       | 58 +++++++++++++++----
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
index 0f19d1f206..def6bbdfeb 100644
--- a/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
+++ b/packages/apidom-ls/src/config/openapi/openapi3_1/documentation.ts
@@ -1,20 +1,58 @@
 const documentation = [
+  {
+    target: 'openapi',
+    docs: '`string`\n\n**REQUIRED**. This string MUST be the [version number](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoVersion) string.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
+  {
+    target: 'jsonSchemaDialect',
+    docs: '`string`\n\nThe default value for the `$schema` keyword within [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject) contained within this OAS document. This MUST be in the form of a URI.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
+  {
+    target: 'webhooks',
+    docs: 'Map[`string`, [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject) &#124; [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\n The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml) is available.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
+  {
+    target: 'security',
+    docs: '#### [[Security Requirement Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#securityRequirementObject)]\n\nA declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
   {
     target: 'servers',
-    docs: '#### [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)\n\nA `server` array to service all operations in this path.\nIf the servers property is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nurl | [`string`] | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.\ndescription | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nvariables | Map[`string`, [Server Variable Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server URL template.\n\n\\\nThis object MAY be extended with [Specification Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n##### Server Object Example\n\n\n\\\nA single server would be described as:\n\n\\\nJSON\n```json\n{\n  "url": "https://development.gigantic-server.com/v1",\n  "description": "Development server"\n}\n```\n\n\n\\\nYAML\n```yaml\nurl: https://development.gigantic-server.com/v1\ndescription: Development server\n```\n\n\\\nThe following shows how multiple servers can be described, for example, at the OpenAPI Object\'s [`servers`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#oasServers):\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://development.gigantic-server.com/v1",\n      "description": "Development server"\n    },\n    {\n      "url": "https://staging.gigantic-server.com/v1",\n      "description": "Staging server"\n    },\n    {\n      "url": "https://api.gigantic-server.com/v1",\n      "description": "Production server"\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://development.gigantic-server.com/v1\n  description: Development server\n- url: https://staging.gigantic-server.com/v1\n  description: Staging server\n- url: https://api.gigantic-server.com/v1\n  description: Production server\n```\n\n\\\nThe following shows how variables can be used for a server configuration:\n\n\\\nJSON\n```json\n{\n  "servers": [\n    {\n      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",\n      "description": "The production API server",\n      "variables": {\n        "username": {\n          "default": "demo",\n          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"\n        },\n        "port": {\n          "enum": [\n            "8443",\n            "443"\n          ],\n          "default": "8443"\n        },\n        "basePath": {\n          "default": "v2"\n        }\n      }\n    }\n  ]\n}\n```\n\n\n\\\nYAML\n```yaml\nservers:\n- url: https://{username}.gigantic-server.com:{port}/{basePath}\n  description: The production API server\n  variables:\n    username:\n      # note! no enum here means it is an open value\n      default: demo\n      description: this value is assigned by the service provider, in this example`gigantic-server.com`\n    port:\n      enum:\n        - \'8443\'\n        - \'443\'\n      default: \'8443\'\n    basePath:\n      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is`v2`\n      default: v2\n```\n',
-    targetSpecs: [
-      { namespace: 'openapi', version: '3.1.0' },
-      { namespace: 'openapi', version: '3.0.0' },
-    ],
+    docs: '#### [[Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject)]\n\nAn array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) with a [url](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverUrl) value of `/`.',
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'tags',
-    docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.\n",
-    targetSpecs: [
-      { namespace: 'openapi', version: '3.1.0' },
-      { namespace: 'openapi', version: '3.0.0' },
-    ],
+    docs: "#### [[Tag Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#tagObject)]\n\nA list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.",
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
+  /**
+   * The following Fixed Fields are provided as reference, but are more
+   * comprehensively described by their respective meta documentation
+   */
+  // {
+  //   target: 'info',
+  //   docs: '#### [Info Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#infoObject)\n\n**REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'paths',
+  //   docs: '#### [Paths Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathsObject)\n\nThe available paths and operations for the API.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'components',
+  //   docs: '#### [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject)\n\nAn element to hold various schemas for the document.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
+  // {
+  //   target: 'externalDocs',
+  //   docs: '#### [External Dcoumentation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#externalDocumentationObject)\n\nAdditional external documentation.',
+  //   targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  // },
 ];
 
 export default documentation;