feat(ls): docs for OpenApi 3.1.0 Discriminator object

packages/apidom-ls/src/config/openapi/config.ts

@@ -1,6 +1,7 @@
 import callbackMeta from './callback/meta';
 import componentsMeta from './components/meta';
 import contactMeta from './contact/meta';
+import discriminatorMeta from './discriminator/meta';
 import encodingMeta from './encoding/meta';
 import exampleMeta from './example/meta';
 import externalDocumentationMeta from './external-documentation/meta';
@@ -44,6 +45,7 @@ export default {
   callback: callbackMeta,
   components: componentsMeta,
   contact: contactMeta,
+  discriminator: discriminatorMeta,
   encoding: encodingMeta,
   example: exampleMeta,
   externalDocumentation: externalDocumentationMeta,

packages/apidom-ls/src/config/openapi/discriminator/documentation.ts

@@ -0,0 +1,23 @@
+const documentation = [
+  {
+    target: 'propertyName',
+    docs: '**REQUIRED**. The name of the property in the payload that will hold the discriminator value.',
+  },
+  {
+    target: 'mapping',
+    docs: 'Map[`string`, `string`]\n\\\n\\\nAn object to hold mappings between payload values and schema names or references.',
+  },
+  {
+    /**
+     * The original documentation has been trimmed in this implementation for readability purposes
+     * A new custom section `Additional documentation topics` has been added,
+     * which refers the reader to the source documentation for additional explanations
+     * Also note, we are cherry picking the documentation section about
+     * `Composition and Inheritance (Polymorphism)`from outside of the Discriminator Object
+     * source documentation.
+     */
+    docs: '#### [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminator-object)\n\nWhen request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.\n\n\\\nWhen using the discriminator, _inline_ schemas will not be considered.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\npropertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value.\nmapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references.\n\n\\\nThis object MAY be extended with [Specification Extensions](#specificationExtensihttps://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions).\n\n\\\nThe discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.\n\n##### [Composition and Inheritance (Polymorphism)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#composition-and-inheritance-polymorphism)\n\nThe OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition.\n`allOf` takes an array of object definitions that are validated *independently* but together compose a single object.\n\n\\\nWhile composition offers model extensibility, it does not imply a hierarchy between the models.\nTo support polymorphism, the OpenAPI Specification adds the `discriminator` field.\nWhen used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.\nAs such, the `discriminator` field MUST be a required field.\nThere are two ways to define the value of a discriminator for an inheriting instance.\n- Use the schema name.\n- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.\nAs such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.\n\n#### Additional documentation topics\n\nFurther explanations of usage can be found in the source documentation for the [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#discriminator-object)\n',
+  },
+];
+
+export default documentation;

packages/apidom-ls/src/config/openapi/discriminator/meta.ts

@@ -0,0 +1,8 @@
+import documentation from './documentation';
+import { FormatMeta } from '../../../apidom-language-types';
+
+const meta: FormatMeta = {
+  documentation,
+};
+
+export default meta;