CLOUDP-305862 - Add missing rule Technical Specifications (#546)

wtrocki · yelizhenden-mdb · lovisaberggren · web-flow · commit d0c6db04c9e2 · 2025-03-18T13:15:19.000+01:00
Co-authored-by: Yeliz Henden &lt;165907936+yelizhenden-mdb@users.noreply.github.com&gt;
Co-authored-by: Lovisa Berggren &lt;59226031+lovisaberggren@users.noreply.github.com&gt;
diff --git a/tools/spectral/ipa/rulesets/IPA-104.yaml b/tools/spectral/ipa/rulesets/IPA-104.yaml
@@ -43,7 +43,6 @@ rules:
   xgen-IPA-104-get-method-response-code-is-200:
     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
@@ -57,7 +56,6 @@ rules:
   xgen-IPA-104-get-method-returns-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
@@ -72,7 +70,6 @@ rules:
   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).
-
       ##### Implementation details
       Rule checks for the following conditions:
         - Applies only to 2xx responses of GET methods on single resources or singleton resources
@@ -87,7 +84,6 @@ rules:
   xgen-IPA-104-get-method-no-request-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
diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml
@@ -9,21 +9,44 @@ functions:
 
 rules:
   xgen-IPA-105-list-method-response-code-is-200:
-    description: 'The List method must return a 200 OK response.'
+    description: |
+      The List method must return a 200 OK response.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to GET methods on resource collection paths
+        - Ignores 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-105-list-method-response-code-is-200'
     severity: warn
     given: '$.paths[*].get'
     then:
       function: 'IPA105ListResponseCodeShouldBe200OK'
   xgen-IPA-105-list-method-no-request-body:
-    description: 'The List method request must not include a body.'
+    description: |
+      The List method request must not include a body.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to GET methods on resource collection paths
+        - Ignores singleton resources
+        - Verifies that the operation object does not contain a requestBody property
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-105-list-method-no-request-body'
     severity: warn
     given: '$.paths[*].get'
     then:
       function: 'IPA105ListMethodHasNoRequestBody'
   xgen-IPA-105-resource-has-list:
-    description: 'APIs must provide a List method for resources.'
+    description: |
+      APIs must provide a List method for resources.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to resource collection paths
+        - Ignores singleton resources
+        - Verifies the resource path has a GET method
+        - Fails if the resource path does not have a GET method
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-105-resource-has-list'
     severity: warn
     given: '$.paths'
@@ -35,13 +58,13 @@ rules:
       The response body of the List method should consist of the same resource object returned by the Get method.
 
       ##### Implementation details
-
-      Validation checks that the List method 200 OK response contains items property with reference to the same schema as the Get method response.
-
-        - Validation applies to List methods for resource collections only
-        - Validation applies to json response content only
-        - Validation ignores responses without schema and non-paginated responses
-          - A response is considered paginated if it contains an array property named `results`
+      Rule checks for the following conditions:
+        - Applies only to resource collection paths with JSON content types
+        - Ignores singleton resources
+        - Ignores responses without a schema or non-paginated responses
+        - A response is considered paginated if it has a schema with a 'results' array property
+        - Verifies that the schema of items in the 'results' array matches the schema used in the Get method response
+        - Fails if the Get method doesn't have a schema reference or if the schemas don't match
         - Validation ignores resources without a Get method
         - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-105-list-method-response-is-get-method-response'
diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml
@@ -11,25 +11,30 @@ functions:
 
 rules:
   xgen-IPA-106-create-method-request-body-is-request-suffixed-object:
-    description: >-
+    description: |
       The Create method request should be a Request suffixed object.
 
       ##### Implementation details
-
-      Validation checks the POST method for resource collection paths.
+      Rule checks for the following conditions:
+        - Applies only to POST methods on resource collection paths (non-singleton resources)
+        - Applies only to JSON content types
+        - Verifies the schema references a predefined schema (not inline)
+        - Confirms the referenced schema name ends with "Request" suffix
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-106-create-method-request-body-is-request-suffixed-object'
     severity: warn
     given: '$.paths[*].post.requestBody.content'
     then:
       field: '@key'
       function: 'IPA106CreateMethodRequestBodyIsRequestSuffixedObject'
   xgen-IPA-106-create-method-should-not-have-query-parameters:
-    description: >-
+    description: |
       Create operations should not use query parameters.
 
       ##### Implementation details
-
-      Validation checks the POST method for resource collection paths.
+      Rule checks for the following conditions:
+        - Applies only to POST methods on resource collection paths (non-singleton resources)
+        - Verifies the operation does not contain query parameters
+        - Ignores specified parameters like 'pretty' and 'envelope' via configuration
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-106-create-method-should-not-have-query-parameters'
     severity: warn
     given: '$.paths[*].post'
@@ -38,7 +43,7 @@ rules:
       functionOptions:
         ignoredValues: ['pretty', 'envelope']
   xgen-IPA-106-create-method-request-body-is-get-method-response:
-    description: >-
+    description: |
       Request body content of the Create method and response content of the Get method should refer to the same resource.
 
       ##### Implementation details
@@ -56,42 +61,46 @@ rules:
       field: '@key'
       function: 'IPA106CreateMethodRequestBodyIsGetResponse'
   xgen-IPA-106-create-method-request-has-no-readonly-fields:
-    description: >-
+    description: |
       Create method Request object must not include fields with readOnly:true.
 
       ##### Implementation details
-
-      Validation checks the POST method for resource collection paths.
+      Rule checks for the following conditions:
+        - Applies only to POST methods on resource collection paths (non-singleton resources)
+        - Applies only to JSON content types
+        - Searches through the request schema to find any properties marked with readOnly attribute
+        - Fails if any readOnly properties are found in the request schema
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-106-create-method-request-has-no-readonly-fields'
     severity: warn
     given: '$.paths[*].post.requestBody.content'
     then:
       field: '@key'
       function: 'IPA106CreateMethodRequestHasNoReadonlyFields'
   xgen-IPA-106-create-method-response-code-is-201:
-    description: >-
+    description: |
       Create methods must return a 201 Created response code.
 
       ##### Implementation details
-
-      Validation checks the POST method for resource collection paths.
+      Rule checks for the following conditions:
+        - Applies only to POST methods on resource collection paths (non-singleton resources)
+        - Verifies the 201 Created response code is present
+        - Fails if the method lacks a 201 Created response or defines a different 2xx status code
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-106-create-method-response-code-is-201'
     severity: warn
     given: '$.paths[*].post'
     then:
       function: 'IPA106CreateMethodResponseCodeIs201Created'
   xgen-IPA-106-create-method-response-is-get-method-response:
-    description: >-
+    description: |
       The response body of the Create method should consist of the same resource object returned by the Get method.
 
       ##### Implementation details
-
-      Validation checks that the Create method 201 Created response contains reference to the same schema as the Get method response.
-
-        - Validation applies to Create methods for resource collections only
-        - Validation applies to json response content only
-        - Validation ignores responses without schema
-        - Validation ignores resources without a Get method
+      Rule checks for the following conditions:
+        - Applies only to POST methods on resource collection paths
+        - Applies only to JSON response content types
+        - Verifies that both Create and Get methods have schema references
+        - Confirms that the Create method 201 response schema reference matches the Get method response schema reference
+        - Ignores resources without a Get method
         - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-106-create-method-response-is-get-method-response'
     severity: warn
diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -3,31 +3,61 @@
 
 rules:
   xgen-IPA-108-delete-response-should-be-empty:
-    description: Delete method response should not have schema reference to object.
+    description: |
+      Delete method response should not have schema reference to object.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to 204 responses in DELETE methods
+        - Verifies that the response does not contain a schema property
+        - Fails if any content type in the response has a defined schema as reference
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-response-should-be-empty'
     severity: warn
     given: $.paths[*].delete.responses[204]
     then:
       function: IPA108DeleteMethodResponseShouldNotHaveSchema
 
   xgen-IPA-108-delete-method-return-204-response:
-    description: DELETE method must return 204 No Content.
+    description: |
+      DELETE method must return 204 No Content.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to all DELETE methods
+         - Verifies the 204 No Content response code is present
+        - Fails if the method lacks a 204 No Content response or defines a different 2xx status code
+        - Ensures no other 2xx response codes are defined
+        - Fails if the 204 status code is missing or if other 2xx responses exist
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-method-return-204-response'
     severity: warn
     given: $.paths[*].delete
     then:
       function: IPA108DeleteMethod204Response
 
   xgen-IPA-108-delete-include-404-response:
-    description: DELETE method must include 404 response and return it when resource not found.
+    description: |
+      DELETE method must include 404 response and return it when resource not found.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to all DELETE methods
+        - Verifies that the method includes a 404 response code
+        - Fails if the 404 status code is missing from the responses
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-include-404-response'
     severity: warn
     given: $.paths[*].delete
     then:
       function: IPA108DeleteMethod404Response
 
   xgen-IPA-108-delete-request-no-body:
-    description: DELETE method must not have request body.
+    description: |
+      DELETE method must not have request body.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to all DELETE methods
+        - Verifies that the operation object does not contain a requestBody property
+        - Fails if any requestBody is defined for the DELETE method
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-request-no-body'
     severity: warn
     given: $.paths[*].delete
diff --git a/tools/spectral/ipa/rulesets/IPA-109.yaml b/tools/spectral/ipa/rulesets/IPA-109.yaml
@@ -7,15 +7,32 @@ functions:
 
 rules:
   xgen-IPA-109-custom-method-must-be-GET-or-POST:
-    description: 'The HTTP method for custom methods must be GET or POST.'
+    description: |
+      The HTTP method for custom methods must be GET or POST.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to paths containing custom method identifiers (with colon format)
+        - Verifies the HTTP methods used are either GET or POST
+        - Fails if any other HTTP methods are used (PUT, DELETE, PATCH, etc.)
+        - Fails if multiple valid methods are defined for the same custom method endpoint
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-109-custom-method-must-be-GET-or-POST'
     severity: error
     given: '$.paths[*]'
     then:
       function: 'IPA109EachCustomMethodMustBeGetOrPost'
 
   xgen-IPA-109-custom-method-must-use-camel-case:
-    description: 'The custom method must use camelCase format.'
+    description: |
+      The custom method must use camelCase format.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to paths containing custom method identifiers (with colon format)
+        - Extracts the method name portion following the colon
+        - Verifies the method name is not empty or blank
+        - Validates that the method name uses proper camelCase formatting
+        - Fails if the method name contains invalid casing (such as snake_case, PascalCase, etc.)
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-109-custom-method-must-use-camel-case'
     severity: error
     given: '$.paths[*]'
diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml
@@ -6,7 +6,16 @@ functions:
 
 rules:
   xgen-IPA-113-singleton-must-not-have-id:
-    description: 'Singleton resources must not have a user-provided or system-generated ID.'
+    description: |
+      Singleton resources must not have a user-provided or system-generated ID.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies only to singleton resources that are identified as resource collection identifiers
+        - Checks that the resource has a GET method defined
+        - Examines all 2xx response schemas from the GET method
+        - Verifies that no schema contains 'id' or '_id' properties in their object definitions
+        - Fails if any response schema contains these identifier properties
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-113-singleton-must-not-have-id'
     severity: warn
     given: '$.paths[*]'
diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml
@@ -6,7 +6,15 @@ functions:
 
 rules:
   xgen-IPA-123-enum-values-must-be-upper-snake-case:
-    description: 'Enum values must be UPPER_SNAKE_CASE.'
+    description: |
+      Enum values must be UPPER_SNAKE_CASE.
+
+      ##### Implementation details
+      Rule checks for the following conditions:
+        - Applies to all enum value arrays defined in the OpenAPI schema
+        - Resolves the schema object that contains the enum values
+        - Validates each enum value individually against the UPPER_SNAKE_CASE pattern
+        - Skips validation if the schema has an exception defined for this rule
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-123-enum-values-must-be-upper-snake-case'
     severity: error
     given: '$..enum'
diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
