CLOUDP-30586: IPA descriptions

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

@@ -22,30 +22,50 @@ rules:
     given: $.paths
     then:
       field: '@key'
-      function: collectionIdentifierCamelCase
+      function: IPA102CollectionIdentifierCamelCase
       functionOptions:
         # Contains list of ignored path params
         ignoredValues: ['v2', 'v1']
 
   xgen-IPA-102-path-alternate-resource-name-path-param:
-    description: 'Paths should alternate between resource names and path params.'
+    description: |
+      Paths should alternate between resource names and path params.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+
+        - Paths must follow a pattern where resource names and path parameters strictly alternate
+        - Even-indexed path segments should be resource names (not path parameters)
+        - Odd-indexed path segments should be path parameters
+        - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-102-path-alternate-resource-name-path-param'
     severity: error
     given: '$.paths'
     then:
       field: '@key'
-      function: 'eachPathAlternatesBetweenResourceNameAndPathParam'
+      function: IPA102EachPathAlternatesBetweenResourceNameAndPathParam
 
   xgen-IPA-102-collection-identifier-pattern:
-    description: Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers.
+    description: |
+      Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+
+        - All path segments that are not path parameters must match pattern `/^[a-z][a-zA-Z0-9]*$/`
+        - Path parameters (inside curly braces) are excluded from validation
+        - Custom methods (segments containing colons) are excluded from validation
+        - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
+        - Each non-parameter path segment must start with a lowercase letter followed by any combination of ASCII letters and numbers
+
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-102-collection-identifier-pattern'
     severity: warn
     given: $.paths
     then:
       field: '@key'
-      function: collectionIdentifierPattern
+      function: IPA102CollectionIdentifierPattern
 
 functions:
-  - collectionIdentifierPattern
-  - eachPathAlternatesBetweenResourceNameAndPathParam
-  - collectionIdentifierCamelCase
+  - IPA102CollectionIdentifierPattern
+  - IPA102EachPathAlternatesBetweenResourceNameAndPathParam
+  - IPA102CollectionIdentifierCamelCase

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

@@ -2,57 +2,98 @@
 # http://go/ipa/104
 
 functions:
-  - eachResourceHasGetMethod
-  - getMethodReturnsSingleResource
-  - getMethodReturnsResponseSuffixedObject
-  - getResponseCodeShouldBe200OK
-  - getMethodResponseHasNoInputFields
-  - getMethodHasNoRequestBody
+  - IPA104EachResourceHasGetMethod
+  - IPA104GetMethodReturnsSingleResource
+  - IPA104GetMethodReturnsResponseSuffixedObject
+  - IPA104GetResponseCodeShouldBe200OK
+  - IPA104GetMethodResponseHasNoInputFields
+  - IPA104GetMethodHasNoRequestBody
 
 rules:
   xgen-IPA-104-resource-has-GET:
-    description: 'APIs must provide a Get method for resources.'
+    description: |
+      APIs must provide a Get method for resources.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Only applies to resource collection identifiers
+        - For singleton resources, verifies the resource has a GET method
+        - For regular resources, verifies there is a single resource path with a GET method
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-resource-has-GET'
     severity: warn
     given: '$.paths'
     then:
       field: '@key'
-      function: 'eachResourceHasGetMethod'
+      function: 'IPA104EachResourceHasGetMethod'
   xgen-IPA-104-get-method-returns-single-resource:
-    description: 'The purpose of the Get method is to return data from a single resource.'
+    description: |
+      The purpose of the Get method is to return data from a single resource.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to 2xx responses of GET methods on single resources or singleton resources
+        - Verifies the response is not an array or paginated result
+        - Different error messages are provided for standard vs singleton resources
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-get-method-returns-single-resource'
     severity: warn
     given: '$.paths[*].get.responses[*].content'
     then:
       field: '@key'
-      function: 'getMethodReturnsSingleResource'
+      function: 'IPA104GetMethodReturnsSingleResource'
   xgen-IPA-104-get-method-response-code-is-200:
-    description: 'The Get method must return a 200 OK response.'
+    description: |
+      The Get method must return a 200 OK response.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to GET methods on single resources or singleton resources
+        - Verifies the 200 OK response code is present
+        - Fails if the method lacks a 200 OK response or defines a different 2xx status code
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-get-method-response-code-is-200'
     severity: warn
     given: '$.paths[*].get'
     then:
-      function: 'getResponseCodeShouldBe200OK'
+      function: 'IPA104GetResponseCodeShouldBe200OK'
   xgen-IPA-104-get-method-returns-response-suffixed-object:
-    description: 'The Get method of a resource should return a "Response" suffixed object.'
+    description: |
+      The Get method of a resource should return a "Response" suffixed object.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to 2xx responses of GET methods on single resources or singleton resources
+        - Verifies the schema references a predefined schema (not inline)
+        - Confirms the referenced schema name ends with "Response" suffix
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-get-method-returns-response-suffixed-object'
     severity: warn
     given: '$.paths[*].get.responses[*].content'
     then:
       field: '@key'
-      function: 'getMethodReturnsResponseSuffixedObject'
+      function: 'IPA104GetMethodReturnsResponseSuffixedObject'
   xgen-IPA-104-get-method-response-has-no-input-fields:
-    description: 'The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields).'
+    description: |
+      The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields).
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to 2xx responses of GET methods on single resources or singleton resources
+        - Searches through the schema to find any properties marked with writeOnly attribute
+        - Fails if any writeOnly properties are found in the response schema
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-get-method-response-has-no-input-fields'
     severity: warn
     given: '$.paths[*].get.responses[*].content'
     then:
       field: '@key'
-      function: 'getMethodResponseHasNoInputFields'
+      function: 'IPA104GetMethodResponseHasNoInputFields'
   xgen-IPA-104-get-method-no-request-body:
-    description: 'The Get method request must not include a body.'
+    description: |
+      The Get method request must not include a body.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to GET methods on single resources or singleton resources
+        - Verifies that the operation object does not contain a requestBody property
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-104-get-method-no-request-body'
     severity: warn
     given: '$.paths[*].get'
     then:
-      function: 'getMethodHasNoRequestBody'
+      function: 'IPA104GetMethodHasNoRequestBody'

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

@@ -2,10 +2,10 @@
 # http://go/ipa/105
 
 functions:
-  - listResponseCodeShouldBe200OK
-  - listMethodHasNoRequestBody
-  - eachResourceHasListMethod
-  - listMethodResponseIsGetMethodResponse
+  - IPA105ListResponseCodeShouldBe200OK
+  - IPA105ListMethodHasNoRequestBody
+  - IPA105EachResourceHasListMethod
+  - IPA105ListMethodResponseIsGetMethodResponse
 
 rules:
   xgen-IPA-105-list-method-response-code-is-200:
@@ -14,22 +14,22 @@ rules:
     severity: warn
     given: '$.paths[*].get'
     then:
-      function: 'listResponseCodeShouldBe200OK'
+      function: 'IPA105ListResponseCodeShouldBe200OK'
   xgen-IPA-105-list-method-no-request-body:
     description: 'The List method request must not include a body.'
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-105-list-method-no-request-body'
     severity: warn
     given: '$.paths[*].get'
     then:
-      function: 'listMethodHasNoRequestBody'
+      function: 'IPA105ListMethodHasNoRequestBody'
   xgen-IPA-105-resource-has-list:
     description: 'APIs must provide a List method for resources.'
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-105-resource-has-list'
     severity: warn
     given: '$.paths'
     then:
       field: '@key'
-      function: 'eachResourceHasListMethod'
+      function: 'IPA105EachResourceHasListMethod'
   xgen-IPA-105-list-method-response-is-get-method-response:
     description: >-
       The response body of the List method should consist of the same resource object returned by the Get method.
@@ -49,4 +49,4 @@ rules:
     given: '$.paths[*].get.responses.200.content'
     then:
       field: '@key'
-      function: 'listMethodResponseIsGetMethodResponse'
+      function: 'IPA105ListMethodResponseIsGetMethodResponse'

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

@@ -2,12 +2,12 @@
 # https://mdb.link/mongodb-atlas-openapi-validation#
 
 functions:
-  - createMethodRequestBodyIsRequestSuffixedObject
-  - createMethodShouldNotHaveQueryParameters
-  - createMethodRequestBodyIsGetResponse
-  - createMethodRequestHasNoReadonlyFields
-  - createMethodResponseCodeIs201Created
-  - createMethodResponseIsGetMethodResponse
+  - IPA106CreateMethodRequestBodyIsRequestSuffixedObject
+  - IPA106CreateMethodShouldNotHaveQueryParameters
+  - IPA106CreateMethodRequestBodyIsGetResponse
+  - IPA106CreateMethodRequestHasNoReadonlyFields
+  - IPA106CreateMethodResponseCodeIs201Created
+  - IPA106CreateMethodResponseIsGetMethodResponse
 
 rules:
   xgen-IPA-106-create-method-request-body-is-request-suffixed-object:
@@ -22,7 +22,7 @@ rules:
     given: '$.paths[*].post.requestBody.content'
     then:
       field: '@key'
-      function: 'createMethodRequestBodyIsRequestSuffixedObject'
+      function: 'IPA106CreateMethodRequestBodyIsRequestSuffixedObject'
   xgen-IPA-106-create-method-should-not-have-query-parameters:
     description: >-
       Create operations should not use query parameters.
@@ -34,7 +34,7 @@ rules:
     severity: warn
     given: '$.paths[*].post'
     then:
-      function: 'createMethodShouldNotHaveQueryParameters'
+      function: 'IPA106CreateMethodShouldNotHaveQueryParameters'
       functionOptions:
         ignoredValues: ['pretty', 'envelope']
   xgen-IPA-106-create-method-request-body-is-get-method-response:
@@ -51,7 +51,7 @@ rules:
     given: '$.paths[*].post.requestBody.content'
     then:
       field: '@key'
-      function: 'createMethodRequestBodyIsGetResponse'
+      function: 'IPA106CreateMethodRequestBodyIsGetResponse'
   xgen-IPA-106-create-method-request-has-no-readonly-fields:
     description: >-
       Create method Request object must not include fields with readOnly:true.
@@ -64,7 +64,7 @@ rules:
     given: '$.paths[*].post.requestBody.content'
     then:
       field: '@key'
-      function: 'createMethodRequestHasNoReadonlyFields'
+      function: 'IPA106CreateMethodRequestHasNoReadonlyFields'
   xgen-IPA-106-create-method-response-code-is-201:
     description: >-
       Create methods must return a 201 Created response code.
@@ -76,7 +76,7 @@ rules:
     severity: warn
     given: '$.paths[*].post'
     then:
-      function: 'createMethodResponseCodeIs201Created'
+      function: 'IPA106CreateMethodResponseCodeIs201Created'
   xgen-IPA-106-create-method-response-is-get-method-response:
     description: >-
       The response body of the Create method should consist of the same resource object returned by the Get method.
@@ -95,4 +95,4 @@ rules:
     given: '$.paths[*].post.responses.201.content'
     then:
       field: '@key'
-      function: 'createMethodResponseIsGetMethodResponse'
+      function: 'IPA106CreateMethodResponseIsGetMethodResponse'

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

@@ -2,8 +2,8 @@
 # http://go/ipa/107
 
 functions:
-  - updateMethodMustNotHaveQueryParams
-  - updateResponseCodeShouldBe200OK
+  - IPA107UpdateMethodMustNotHaveQueryParams
+  - IPA107UpdateResponseCodeShouldBe200OK
 
 rules:
   xgen-IPA-107-put-must-not-have-query-params:
@@ -20,7 +20,7 @@ rules:
     severity: warn
     given: '$.paths[*].put'
     then:
-      function: 'updateMethodMustNotHaveQueryParams'
+      function: 'IPA107UpdateMethodMustNotHaveQueryParams'
       functionOptions:
         ignoredValues: ['pretty', 'envelope']
   xgen-IPA-107-patch-must-not-have-query-params:
@@ -37,7 +37,7 @@ rules:
     severity: warn
     given: '$.paths[*].patch'
     then:
-      function: 'updateMethodMustNotHaveQueryParams'
+      function: 'IPA107UpdateMethodMustNotHaveQueryParams'
       functionOptions:
         ignoredValues: ['pretty', 'envelope']
   xgen-IPA-107-put-method-response-code-is-200:
@@ -53,7 +53,7 @@ rules:
     severity: warn
     given: '$.paths[*].put'
     then:
-      function: 'updateResponseCodeShouldBe200OK'
+      function: 'IPA107UpdateResponseCodeShouldBe200OK'
   xgen-IPA-107-patch-method-response-code-is-200:
     description: >-
       The Update method response status code should be 200 OK.
@@ -67,4 +67,4 @@ rules:
     severity: warn
     given: '$.paths[*].patch'
     then:
-      function: 'updateResponseCodeShouldBe200OK'
+      function: 'IPA107UpdateResponseCodeShouldBe200OK'

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

@@ -8,34 +8,34 @@ rules:
     severity: warn
     given: $.paths[*].delete.responses[204]
     then:
-      function: deleteMethodResponseShouldNotHaveSchema
+      function: IPA108DeleteMethodResponseShouldNotHaveSchema
 
   xgen-IPA-108-delete-method-return-204-response:
     description: DELETE method must return 204 No Content.
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-method-return-204-response'
     severity: warn
     given: $.paths[*].delete
     then:
-      function: deleteMethod204Response
+      function: IPA108DeleteMethod204Response
 
   xgen-IPA-108-delete-include-404-response:
     description: DELETE method must include 404 response and return it when resource not found.
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-include-404-response'
     severity: warn
     given: $.paths[*].delete
     then:
-      function: deleteMethod404Response
+      function: IPA108DeleteMethod404Response
 
   xgen-IPA-108-delete-request-no-body:
     description: DELETE method must not have request body.
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-request-no-body'
     severity: warn
     given: $.paths[*].delete
     then:
-      function: deleteMethodNoRequestBody
+      function: IPA108DeleteMethodNoRequestBody
 
 functions:
-  - deleteMethodResponseShouldNotHaveSchema
-  - deleteMethod204Response
-  - deleteMethodNoRequestBody
-  - deleteMethod404Response
+  - IPA108DeleteMethodResponseShouldNotHaveSchema
+  - IPA108DeleteMethod204Response
+  - IPA108DeleteMethodNoRequestBody
+  - IPA108DeleteMethod404Response