CLOUDP-305862: IPA 106 documentation standard

tools/spectral/ipa/__tests__/exceptionExtensionFormat.test.js → tools/spectral/ipa/__tests__/IPA105exceptionExtensionFormat.test.js

@@ -51,25 +51,25 @@ testRule('xgen-IPA-005-exception-extension-format', [
     errors: [
       {
         code: 'xgen-IPA-005-exception-extension-format',
-        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5',
+        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102',
         path: ['paths', '/path1', 'x-xgen-IPA-exception'],
         severity: DiagnosticSeverity.Warning,
       },
       {
         code: 'xgen-IPA-005-exception-extension-format',
-        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5',
+        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102',
         path: ['paths', '/path2', 'x-xgen-IPA-exception', 'xgen-IPA-100-rule-name'],
         severity: DiagnosticSeverity.Warning,
       },
       {
         code: 'xgen-IPA-005-exception-extension-format',
-        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5',
+        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102',
         path: ['paths', '/path3', 'x-xgen-IPA-exception', 'invalid-rule-name'],
         severity: DiagnosticSeverity.Warning,
       },
       {
         code: 'xgen-IPA-005-exception-extension-format',
-        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5',
+        message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102',
         path: ['paths', '/path4', 'x-xgen-IPA-exception', 'xgen-IPA-100-rule-name'],
         severity: DiagnosticSeverity.Warning,
       },

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

@@ -2,13 +2,20 @@
 # http://go/ipa/5
 
 functions:
-  - exceptionExtensionFormat
+  - IPA105ExceptionExtensionFormat
 
 rules:
   xgen-IPA-005-exception-extension-format:
-    description: 'IPA exception extensions must follow the correct format. http://go/ipa/5'
-    message: '{{error}} http://go/ipa/5'
+    description: |
+      IPA exception extensions must follow the correct format. http://go/ipa/5
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Exception rule names must start with 'xgen-IPA-' prefix
+        - Each exception must include a non-empty reason as a string
+        - This rule itself does not allow exceptions
+    message: '{{error}} http://go/ipa-spectral#IPA-102'
     severity: error
     given: '$..x-xgen-IPA-exception'
     then:
-      function: 'exceptionExtensionFormat'
+      function: 'IPA105ExceptionExtensionFormat'

tools/spectral/ipa/rulesets/README.md

@@ -17,6 +17,12 @@ Rule is based on [http://go/ipa/IPA-5](http://go/ipa/IPA-5).
  ![error](https://img.shields.io/badge/error-red) 
 IPA exception extensions must follow the correct format. http://go/ipa/5
 
+##### Implementation details
+Rule checks for the following conditions:
+  - Exception rule names must start with 'xgen-IPA-' prefix
+  - Each exception must include a non-empty reason as a string
+  - This rule itself does not allow exceptions
+
 
 
 ### IPA-102
@@ -27,7 +33,6 @@ Rule is based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102).
 
  ![error](https://img.shields.io/badge/error-red) 
 Paths should alternate between resource names and path params. http://go/ipa/102
-
 #### xgen-IPA-102-collection-identifier-camelCase
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
@@ -44,14 +49,12 @@ Collection identifiers must be in camelCase.
    - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
    - Double slashes (//) are not allowed in paths
 
-
 #### xgen-IPA-102-collection-identifier-pattern
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers. http://go/ipa/102
 
 
-
 ### IPA-104
 
 Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104).
@@ -60,34 +63,28 @@ Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104).
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 APIs must provide a Get method for resources. http://go/ipa/104
-
 #### xgen-IPA-104-get-method-returns-single-resource
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The purpose of the Get method is to return data from a single resource. http://go/ipa/104
-
 #### xgen-IPA-104-get-method-response-code-is-200
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The Get method must return a 200 OK response. http://go/ipa/104
-
 #### xgen-IPA-104-get-method-returns-response-suffixed-object
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The Get method of a resource should return a "Response" suffixed object. http://go/ipa/104
-
 #### xgen-IPA-104-get-method-response-has-no-input-fields
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields). http://go/ipa/104
-
 #### xgen-IPA-104-get-method-no-request-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The Get method request must not include a body. http://go/ipa/104
 
 
-
 ### IPA-105
 
 Rule is based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105).
@@ -96,19 +93,16 @@ Rule is based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105).
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The List method must return a 200 OK response. http://go/ipa/105
-
 #### xgen-IPA-105-list-method-no-request-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The List method request must not include a body. http://go/ipa/105
-
 #### xgen-IPA-105-resource-has-list
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 APIs must provide a List method for resources. http://go/ipa/105
 
 
-
 ### IPA-106
 
 Rule is based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106).
@@ -117,29 +111,24 @@ Rule is based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106).
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 The Create method request should be a Request suffixed object. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
-
 #### xgen-IPA-106-create-method-should-not-have-query-parameters
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Create operations should not use query parameters. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
-
 #### xgen-IPA-106-create-method-request-body-is-get-method-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly/writeOnly properties will be ignored.   This rule applies only to POST requests targeting resource collection URIs.
-
 #### xgen-IPA-106-create-method-request-has-no-readonly-fields
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Create method Request object must not include fields with readOnly:true. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
-
 #### xgen-IPA-106-create-method-response-code-is-201
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Create methods must return a 201 Created response code. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs.
 
 
-
 ### IPA-108
 
 Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108).
@@ -148,24 +137,20 @@ Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108).
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 Delete method response should not have schema reference to object. http://go/ipa/108
-
 #### xgen-IPA-108-delete-method-return-204-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 DELETE method must return 204 No Content. http://go/ipa/108
-
 #### xgen-IPA-108-delete-include-404-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 DELETE method must include 404 response and return it when resource not found. http://go/ipa/108
-
 #### xgen-IPA-108-delete-request-no-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 DELETE method must not have request body. http://go/ipa/108
 
 
-
 ### IPA-109
 
 Rule is based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109).
@@ -174,14 +159,12 @@ Rule is based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109).
 
  ![error](https://img.shields.io/badge/error-red) 
 The HTTP method for custom methods must be GET or POST. http://go/ipa/109
-
 #### xgen-IPA-109-custom-method-must-use-camel-case
 
  ![error](https://img.shields.io/badge/error-red) 
 The custom method must use camelCase format. http://go/ipa/109
 
 
-
 ### IPA-113
 
 Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113).
@@ -192,7 +175,6 @@ Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113).
 Singleton resources must not have a user-provided or system-generated ID. http://go/ipa/113
 
 
-
 ### IPA-123
 
 Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123).
@@ -204,4 +186,3 @@ Enum values must be UPPER_SNAKE_CASE. http://go/ipa/123
 
 
 
-

tools/spectral/ipa/scripts/generateRulesetReadme.js

@@ -60,7 +60,7 @@ function generateRulesetSections(rules) {
 
   sortedRuleEntries.forEach((rule) => {
     const severityFormatted = formatSeverity(rule.severity);
-    sections += `#### ${rule.name}\n\n ${severityFormatted} \n${rule.description}\n\n`;
+    sections += `#### ${rule.name}\n\n ${severityFormatted} \n${rule.description}\n`;
   });
 
   return sections;