fix(ipa): include schema descriptions in IPA117 rules

Author: lovisaberggren

tools/spectral/ipa/__tests__/IPA117DescriptionEndsWithPeriod.test.js

@@ -8,6 +8,7 @@ testRule('xgen-IPA-117-description-ends-with-period', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description.',
             properties: {
               id: {
                 description: 'Description.',
@@ -25,6 +26,7 @@ testRule('xgen-IPA-117-description-ends-with-period', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description',
             properties: {
               noPeriod: {
                 description: 'Description',
@@ -35,6 +37,12 @@ testRule('xgen-IPA-117-description-ends-with-period', [
       },
     },
     errors: [
+      {
+        code: 'xgen-IPA-117-description-ends-with-period',
+        message: 'Descriptions must end with a full stop(.).',
+        path: ['components', 'schemas', 'Schema'],
+        severity: DiagnosticSeverity.Error,
+      },
       {
         code: 'xgen-IPA-117-description-ends-with-period',
         message: 'Descriptions must end with a full stop(.).',
@@ -49,6 +57,7 @@ testRule('xgen-IPA-117-description-ends-with-period', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description\n| Table |',
             properties: {
               noPeriod: {
                 description: 'Description\n| Table |',
@@ -66,6 +75,10 @@ testRule('xgen-IPA-117-description-ends-with-period', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description',
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-117-description-ends-with-period': 'reason',
+            },
             properties: {
               noPeriod: {
                 description: 'Description',

tools/spectral/ipa/__tests__/IPA117DescriptionMustNotUseHtml.test.js

@@ -7,6 +7,7 @@ testRule('xgen-IPA-117-description-must-not-use-html', [
     document: {
       components: {
         schemas: {
+          description: 'Must be < 250 characters.',
           Schema: {
             properties: {
               valid: {
@@ -31,6 +32,7 @@ testRule('xgen-IPA-117-description-must-not-use-html', [
       components: {
         schemas: {
           Schema: {
+            description: '<a>Description</a>',
             properties: {
               html: {
                 description: '<a>Description</a>',
@@ -50,6 +52,12 @@ testRule('xgen-IPA-117-description-must-not-use-html', [
       },
     },
     errors: [
+      {
+        code: 'xgen-IPA-117-description-must-not-use-html',
+        message: 'Descriptions must not use raw HTML.',
+        path: ['components', 'schemas', 'Schema'],
+        severity: DiagnosticSeverity.Error,
+      },
       {
         code: 'xgen-IPA-117-description-must-not-use-html',
         message: 'Descriptions must not use raw HTML.',
@@ -83,6 +91,10 @@ testRule('xgen-IPA-117-description-must-not-use-html', [
       components: {
         schemas: {
           Schema: {
+            description: '<a>Description</a>',
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-117-description-must-not-use-html': 'reason',
+            },
             properties: {
               html: {
                 description: '<a>Description</a>',

tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseLinks.test.js

@@ -8,6 +8,7 @@ testRule('xgen-IPA-117-description-should-not-use-inline-links', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description.',
             properties: {
               valid: {
                 description: 'Description.',
@@ -37,6 +38,7 @@ testRule('xgen-IPA-117-description-should-not-use-inline-links', [
       components: {
         schemas: {
           Schema: {
+            description: 'Hello [world](https://www.mongodb.com).',
             properties: {
               invalidLink: {
                 description: 'Hello [world](https://www.mongodb.com).',
@@ -50,6 +52,13 @@ testRule('xgen-IPA-117-description-should-not-use-inline-links', [
       },
     },
     errors: [
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-links',
+        message:
+          'Descriptions should not include inline links. Use the externalDocumentation property instead, see https://swagger.io/specification/#external-documentation-object.',
+        path: ['components', 'schemas', 'Schema'],
+        severity: DiagnosticSeverity.Error,
+      },
       {
         code: 'xgen-IPA-117-description-should-not-use-inline-links',
         message:
@@ -72,6 +81,10 @@ testRule('xgen-IPA-117-description-should-not-use-inline-links', [
       components: {
         schemas: {
           Schema: {
+            description: 'Hello [world](https://www.mongodb.com).',
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-117-description-should-not-use-inline-links': 'reason',
+            },
             properties: {
               invalidLink: {
                 description: 'Hello [world](https://www.mongodb.com).',

tools/spectral/ipa/__tests__/IPA117DescriptionShouldNotUseTables.test.js

@@ -8,6 +8,7 @@ testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
       components: {
         schemas: {
           Schema: {
+            description: 'Schema for request | response',
             properties: {
               valid: {
                 description: 'Description.',
@@ -28,6 +29,7 @@ testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
       components: {
         schemas: {
           Schema: {
+            description: '|Title|\n|-----|\n|Description|',
             properties: {
               table: {
                 description: '|Title|\n|-----|\n|Description|',
@@ -50,6 +52,13 @@ testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
       },
     },
     errors: [
+      {
+        code: 'xgen-IPA-117-description-should-not-use-inline-tables',
+        message:
+          'Descriptions should not include inline tables. Tables may not work well with all tools, in particular generated client code.',
+        path: ['components', 'schemas', 'Schema'],
+        severity: DiagnosticSeverity.Error,
+      },
       {
         code: 'xgen-IPA-117-description-should-not-use-inline-tables',
         message:
@@ -93,6 +102,10 @@ testRule('xgen-IPA-117-description-should-not-use-inline-tables', [
       components: {
         schemas: {
           Schema: {
+            description: '|Title|\n|-----|\n|Description|',
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-117-description-should-not-use-inline-tables': 'reason',
+            },
             properties: {
               table: {
                 description: '|Title|\n|-----|\n|Description|',

tools/spectral/ipa/__tests__/IPA117DescriptionStartsWithUpperCase.test.js

@@ -8,6 +8,7 @@ testRule('xgen-IPA-117-description-starts-with-uppercase', [
       components: {
         schemas: {
           Schema: {
+            description: 'Description',
             properties: {
               id: {
                 description: 'Description',
@@ -25,6 +26,7 @@ testRule('xgen-IPA-117-description-starts-with-uppercase', [
       components: {
         schemas: {
           Schema: {
+            description: 'description',
             properties: {
               noUpperCase: {
                 description: 'description',
@@ -35,6 +37,12 @@ testRule('xgen-IPA-117-description-starts-with-uppercase', [
       },
     },
     errors: [
+      {
+        code: 'xgen-IPA-117-description-starts-with-uppercase',
+        message: 'Descriptions must start with Uppercase.',
+        path: ['components', 'schemas', 'Schema'],
+        severity: DiagnosticSeverity.Error,
+      },
       {
         code: 'xgen-IPA-117-description-starts-with-uppercase',
         message: 'Descriptions must start with Uppercase.',
@@ -49,6 +57,10 @@ testRule('xgen-IPA-117-description-starts-with-uppercase', [
       components: {
         schemas: {
           Schema: {
+            description: 'description',
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-117-description-starts-with-uppercase': 'reason',
+            },
             properties: {
               noUpperCase: {
                 description: 'description',

tools/spectral/ipa/ipa-spectral.yaml

@@ -148,3 +148,32 @@ overrides:
       - '**#/components/schemas/AWSHardwareSpec20240805/properties/ebsVolumeType'
     rules:
       xgen-IPA-112-field-names-are-camel-case: 'off'
+  - files: # To be removed in CLOUDP-338116
+      - '**#/components/schemas/AtlasResourcePolicyAuditForNdsGroup'
+      - '**#/components/schemas/AtlasResourcePolicyAuditForOrg'
+      - '**#/components/schemas/ChartsAudit'
+      - '**#/components/schemas/DefaultLimit'
+      - '**#/components/schemas/ObjectCreated'
+      - '**#/components/schemas/PinnedNamespaces'
+      - '**#/components/schemas/RequestAccepted'
+      - '**#/components/schemas/StreamsStartStreamProcessorWith'
+      - '**#/components/schemas/TextSearchIndexCreateRequest'
+      - '**#/components/schemas/VectorSearchIndexCreateRequest'
+      - '**#/components/schemas/AtlasTenantClusterUpgradeRequest20240805'
+      - '**#/components/schemas/StreamsModifyStreamProcessor'
+      - '**#/components/schemas/EventTypeDetails'
+      - '**#/components/schemas/LegacyAtlasTenantClusterUpgradeRequest'
+    rules:
+      xgen-IPA-117-description-ends-with-period: 'off'
+  - files: # To be removed in CLOUDP-338116
+      - '**#/components/schemas/CustomCriteriaView'
+      - '**#/components/schemas/ExtraRetentionSetting'
+      - '**#/components/schemas/MetricDataPoint'
+      - '**#/components/schemas/MetricDataPoint_Atlas'
+      - '**#/components/schemas/DateCriteriaView'
+    rules:
+      xgen-IPA-117-description-starts-with-uppercase: 'off'
+  - files:
+      - '**#/components/schemas/NewRelic'
+    rules:
+      xgen-IPA-117-description-must-not-use-html: 'off'

tools/spectral/ipa/rulesets/IPA-117.yaml

@@ -15,13 +15,21 @@ functions:
 aliases:
   OperationObject:
     - '$.paths[*][get,put,post,delete,options,head,patch,trace]'
+  RequiredDescribableObjects:
+    - '$.tags[*]'
+    - '#OperationObject'
+    - '#OperationObject.parameters[*]'
+    - '#OperationObject..content..properties[*]'
+    - '$.components.schemas..properties[*]'
+    - '$.components.parameters[*]'
   DescribableObjects:
     - '$.tags[*]'
     - '#OperationObject'
     - '#OperationObject.parameters[*]'
     - '#OperationObject..content..properties[*]'
     - '$.components.schemas..properties[*]'
     - '$.components.parameters[*]'
+    - '$.components.schemas[*]'
 
 rules:
   xgen-IPA-117-description:
@@ -41,7 +49,7 @@ rules:
     severity: error
     given:
       - '$.info'
-      - '#DescribableObjects'
+      - '#RequiredDescribableObjects'
     then:
       function: 'IPA117HasDescription'
   xgen-IPA-117-description-starts-with-uppercase: