OpenAPI 3.0.x rules finalization

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

@@ -793,6 +793,25 @@ enum ApilintCodes {
   OPENAPI3_0_LINK_FIELD_DESCRIPTION_TYPE = 5270300,
   OPENAPI3_0_LINK_FIELD_SERVER_TYPE = 5270400,
 
+  OPENAPI3_0_HEADER = 5280000,
+  OPENAPI3_0_HEADER_FIELD_DESCRIPTION_TYPE = 5280100,
+  OPENAPI3_0_HEADER_FIELD_REQUIRED_TYPE = 5280200,
+  OPENAPI3_0_HEADER_FIELD_DEPRECATED_TYPE = 5280300,
+  OPENAPI3_0_HEADER_FIELD_ALLOW_EMPTY_VALUE_TYPE = 5280400,
+  OPENAPI3_0_HEADER_FIELD_STYLE_TYPE = 5280500,
+  OPENAPI3_0_HEADER_FIELD_EXPLODE_TYPE = 5280600,
+  OPENAPI3_0_HEADER_FIELD_ALLOW_RESERVED_TYPE = 5280700,
+  OPENAPI3_0_HEADER_FIELD_SCHEMA_TYPE = 5280800,
+  OPENAPI3_0_HEADER_FIELD_EXAMPLES_VALUES_TYPE = 5280900,
+  OPENAPI3_0_HEADER_FIELD_CONTENT_VALUES_TYPE = 5281000,
+
+  OPENAPI3_0_RESPONSE = 5290000,
+  OPENAPI3_0_RESPONSE_FIELD_DESCRIPTION_TYPE = 5290100,
+  OPENAPI3_0_RESPONSE_FIELD_DESCRIPTION_REQUIRED,
+  OPENAPI3_0_RESPONSE_FIELD_HEADERS_VALUES_TYPE = 5290200,
+  OPENAPI3_0_RESPONSE_FIELD_CONTENT_VALUES_TYPE = 5290300,
+  OPENAPI3_0_RESPONSE_FIELD_LINKS_VALUES_TYPE = 5290400,
+
   OPENAPI3_1 = 7000000,
 
   OPENAPI3_1_OPENAPI_VALUE_PATTERN_3_1_0 = 7000100,

packages/apidom-ls/src/config/openapi/discriminator/lint/allowed-fields-3-0.ts

@@ -10,6 +10,12 @@ const allowedFields3_0Lint: LinterMeta = {
   linterFunction: 'allowedFields',
   linterParams: [['propertyName', 'mapping']],
   marker: 'key',
+  targetSpecs: [
+    { namespace: 'openapi', version: '3.0.0' },
+    { namespace: 'openapi', version: '3.0.1' },
+    { namespace: 'openapi', version: '3.0.2' },
+    { namespace: 'openapi', version: '3.0.3' },
+  ],
 };
 
 export default allowedFields3_0Lint;

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

@@ -0,0 +1,224 @@
+import {
+  ApidomCompletionItem,
+  CompletionFormat,
+  CompletionType,
+} from '../../../apidom-language-types';
+
+const completion: ApidomCompletionItem[] = [
+  {
+    label: '$ref',
+    insertText: '\\$ref',
+    kind: 14,
+    format: CompletionFormat.QUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value: 'A reference to a Header',
+    },
+  },
+  {
+    label: 'description',
+    insertText: 'description',
+    kind: 14,
+    format: CompletionFormat.QUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'A brief description of the header. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.',
+    },
+  },
+  {
+    label: 'required',
+    insertText: 'required',
+    kind: 14,
+    format: CompletionFormat.UNQUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'Determines whether this header is mandatory. This property MAY be included and its default value is `false`.',
+    },
+  },
+  {
+    label: 'deprecated',
+    insertText: 'deprecated',
+    kind: 14,
+    format: CompletionFormat.UNQUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'Specifies that a header is deprecated and SHOULD be transitioned out of usage. Default value is `false`.',
+    },
+  },
+  {
+    label: 'allowEmptyValue',
+    insertText: 'allowEmptyValue',
+    kind: 14,
+    format: CompletionFormat.UNQUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        "Doesn't apply for headers. Default value is `false`. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.",
+    },
+  },
+  {
+    label: 'style',
+    insertText: 'style',
+    kind: 14,
+    format: CompletionFormat.QUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value: 'Describes how the header value will be serialized. Default value: `simple`.',
+    },
+  },
+  {
+    label: 'explode',
+    insertText: 'explode',
+    kind: 14,
+    format: CompletionFormat.UNQUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'When this is true, header values of type array or object generate separate headers for each value of the array or key-value pair of the map. The default value is `false`.',
+    },
+  },
+  {
+    label: 'allowReserved',
+    insertText: 'allowReserved',
+    kind: 14,
+    format: CompletionFormat.UNQUOTED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        "Determines whether the header 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 has no effect and the default value is `false`.",
+    },
+  },
+  {
+    label: 'schema',
+    insertText: 'schema',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        '[Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)\n\\\n\\\nThe schema defining the type used for the header.',
+    },
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
+  {
+    label: 'schema',
+    insertText: 'schema',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        '[Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schemaObject)\n\\\n\\\nThe schema defining the type used for the header.',
+    },
+    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
+  },
+  {
+    label: 'example',
+    insertText: 'example',
+    kind: 14,
+    format: CompletionFormat.UNDEFINED,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        "Example of the header'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.",
+    },
+  },
+  {
+    label: 'examples',
+    insertText: 'examples',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)]\n\\\n\\\nExamples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
+  {
+    label: 'examples',
+    insertText: 'examples',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\\\n\\\nExamples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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' }],
+  },
+  {
+    label: 'content',
+    insertText: 'content',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the header. The key is the media type and the value describes it. The map MUST only contain one entry.',
+    },
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
+  {
+    label: 'content',
+    insertText: 'content',
+    kind: 14,
+    format: CompletionFormat.OBJECT,
+    type: CompletionType.PROPERTY,
+    insertTextFormat: 2,
+    documentation: {
+      kind: 'markdown',
+      value:
+        'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the header. 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' }],
+  },
+];
+
+export default completion;

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

@@ -1,21 +1,28 @@
+/**
+ * Omitted fixed fields for OpenAPI 3.1.0:
+ *  - schema
+ *
+ * Field omission reason: omitted fields do have a non-union type. Thus,
+ * documentation for these fields doesn't need to be specified here and will
+ * come directly from the type itself. Description of these fields doesn't
+ * contain significant information.
+ */
 const documentation = [
   {
     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.',
+    docs: 'A brief description of the header. 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 header is mandatory. This property MAY be included and its default value is `false`.',
-    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'deprecated',
-    docs: 'Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.',
+    docs: 'Specifies that a header is deprecated and SHOULD be transitioned out of usage. Default value is `false`.',
   },
   {
     target: 'allowEmptyValue',
-    docs: 'Sets the ability to pass empty-valued headers.  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' }],
+    docs: "Doesn't apply for headers. Default value is `false`. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.",
   },
   {
     target: 'style',
@@ -24,21 +31,64 @@ const documentation = [
   {
     target: 'explode',
     docs: 'When this is true, header values of type array or object generate separate headers for each value of the array or key-value pair of the map. The default value is `false`.',
-    targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],
   },
   {
     target: 'allowReserved',
     docs: "Determines whether the header 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 has no effect and the default value is `false`.",
   },
+  {
+    target: 'schema',
+    docs: '[Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)\n\\\n\\\nThe schema defining the type used for the header.',
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
   {
     target: 'example',
     docs: "Example of the header'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',
-    docs: "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\\\n\\\nExamples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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",
+    docs: "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#referenceObject)]\n\\\n\\\nExamples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
+  {
+    target: 'examples',
+    docs: "Map[`string`, [Example Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#exampleObject) | [Reference Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject)]\n\\\n\\\nExamples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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: 'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the header. The key is the media type and the value describes it. The map MUST only contain one entry.',
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
+  {
+    target: 'content',
+    docs: 'Map[string, [Media Type Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#mediaTypeObject)]\n\\\n\\\nA map containing the representations for the header. 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: '#### [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#headerObject)\n\nThe Header Object follows the structure of the [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject) with the following changes:\n\n1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.\n1. `in` MUST NOT be specified, it is implicitly in `header`.\n1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterStyle)).\n\n##### Header Object Example\n\nA simple header of type `integer`:\n\n\n\\\nJSON\n```json\n{\n  "description": "The number of allowed requests in the current period",\n  "schema": {\n    "type": "integer"\n  }\n}\n```\n\n\n\\\nYAML\n```yaml\ndescription: The number of allowed requests in the current period\nschema:\n  type: integer\n```',
+    targetSpecs: [
+      { namespace: 'openapi', version: '3.0.0' },
+      { namespace: 'openapi', version: '3.0.1' },
+      { namespace: 'openapi', version: '3.0.2' },
+      { namespace: 'openapi', version: '3.0.3' },
+    ],
+  },
   {
     docs: '#### [Header Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#headerObject)\n\nThe Header Object follows the structure of the [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject) with the following changes:\n\n 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.\n  2. `in` MUST NOT be specified, it is implicitly in `header`.\n  3. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle)).\n\n##### Header Object Example\n\n\\\nA simple header of type `integer`:\n\n\\\nJSON\n```json\n{\n  "description": "The number of allowed requests in the current period",\n  "schema": {\n    "type": "integer"\n  }\n}\n```\n\n\\\nYAML\n```yaml\ndescription: The number of allowed requests in the current period\nschema:\n  type: integer\n```\n',
     targetSpecs: [{ namespace: 'openapi', version: '3.1.0' }],

packages/apidom-ls/src/config/openapi/header/lint/allow-empty-value--type.ts

@@ -0,0 +1,16 @@
+import ApilintCodes from '../../../codes';
+import { LinterMeta } from '../../../../apidom-language-types';
+
+const allowEmptyValueTypeLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI3_0_HEADER_FIELD_ALLOW_EMPTY_VALUE_TYPE,
+  source: 'apilint',
+  message: 'allowEmptyValue must be a boolean',
+  severity: 1,
+  linterFunction: 'apilintType',
+  linterParams: ['boolean'],
+  marker: 'value',
+  target: 'allowEmptyValue',
+  data: {},
+};
+
+export default allowEmptyValueTypeLint;

packages/apidom-ls/src/config/openapi/header/lint/allow-reserved--type.ts

@@ -0,0 +1,16 @@
+import ApilintCodes from '../../../codes';
+import { LinterMeta } from '../../../../apidom-language-types';
+
+const allowReservedTypeLint: LinterMeta = {
+  code: ApilintCodes.OPENAPI3_0_HEADER_FIELD_ALLOW_RESERVED_TYPE,
+  source: 'apilint',
+  message: 'allowReserved must be a boolean',
+  severity: 1,
+  linterFunction: 'apilintType',
+  linterParams: ['boolean'],
+  marker: 'value',
+  target: 'allowReserved',
+  data: {},
+};
+
+export default allowReservedTypeLint;