From 98edacdafcd334a7e9a28ade64ea23fbda68abcc Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:06:17 +0100
Subject: [PATCH 01/15] fix: IPA-104 descriptions

---
 tools/spectral/ipa/rulesets/IPA-104.yaml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-104.yaml b/tools/spectral/ipa/rulesets/IPA-104.yaml
index c50a092d6a..7a9af876c9 100644
--- 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

From d4d6746306f43579b3fd1ad14d9c123773498da1 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:17:41 +0100
Subject: [PATCH 02/15] fix: IPA-105

---
 tools/spectral/ipa/rulesets/IPA-105.yaml | 44 ++++++++++++++++++------
 tools/spectral/ipa/rulesets/README.md    | 38 +++++++++++++++-----
 2 files changed, 63 insertions(+), 19 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml
index db004218a0..67ee1ed360 100644
--- 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,14 +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`
-        - Validation ignores resources without a Get method
+      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
         - 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'
     severity: warn
diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
index 18c892ff68..70869b63b1 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -153,26 +153,48 @@ 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.
+
+##### 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
+
 #### 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.
+
+##### 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
+
 #### xgen-IPA-105-resource-has-list
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
+
 #### xgen-IPA-105-list-method-response-is-get-method-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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`
-  - Validation ignores resources without a Get method
+##### Implementation details 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
   - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
 
 

From e07cd899e687eea3555a623325a5ec0db4648d5f Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:27:15 +0100
Subject: [PATCH 03/15] IPA-106

---
 tools/spectral/ipa/rulesets/IPA-106.yaml | 51 ++++++++++++++----------
 1 file changed, 30 insertions(+), 21 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml
index b378cee4bd..1de05b4562 100644
--- a/tools/spectral/ipa/rulesets/IPA-106.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-106.yaml
@@ -11,12 +11,15 @@ 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'
@@ -24,12 +27,14 @@ rules:
       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,12 +61,15 @@ 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 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'
@@ -69,29 +77,30 @@ rules:
       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

From 6dadb69a9d16c88f511314d437e1d119977b445e Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:32:36 +0100
Subject: [PATCH 04/15] IPA-108

---
 tools/spectral/ipa/rulesets/IPA-108.yaml | 37 +++++++++--
 tools/spectral/ipa/rulesets/README.md    | 80 +++++++++++++++++++-----
 2 files changed, 99 insertions(+), 18 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
index 750e85ae29..5f32ccb2ad 100644
--- a/tools/spectral/ipa/rulesets/IPA-108.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -3,7 +3,14 @@
 
 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 of DELETE methods
+        - Verifies that the response does not contain a schema property
+        - Fails if any content type in the response includes a schema definition
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-response-should-be-empty'
     severity: warn
     given: $.paths[*].delete.responses[204]
@@ -11,7 +18,15 @@ rules:
       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 that the operation includes a 204 response
+        - Ensures there are no other 2xx response codes defined
+        - Fails if 204 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
@@ -19,7 +34,14 @@ rules:
       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 operation includes a 404 response
+        - Fails if the 404 status code is not defined in the responses object
     message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-include-404-response'
     severity: warn
     given: $.paths[*].delete
@@ -27,7 +49,14 @@ rules:
       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 does not contain a requestBody property
+        - Fails if a requestBody is defined for the DELETE operation
     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/README.md b/tools/spectral/ipa/rulesets/README.md
index 70869b63b1..5373bd1214 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -104,7 +104,6 @@ Rule checks for the following conditions:
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
@@ -115,7 +114,6 @@ Rule checks for the following conditions:
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
@@ -126,7 +124,6 @@ Rule checks for the following conditions:
 
  ![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).
-
 ##### Implementation details
 Rule checks for the following conditions:
   - Applies only to 2xx responses of GET methods on single resources or singleton resources
@@ -137,7 +134,6 @@ Rule checks for the following conditions:
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
@@ -206,51 +202,78 @@ 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.
+
 ##### 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
+
 #### 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.
+
 ##### 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
+
 #### 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.
+
 ##### Implementation details
+
 Validation checks the POST method for resource collection paths.
   - Validation ignores resources without a Get method.
   - `readOnly:true` properties of Get method response will be ignored. 
   - `writeOnly:true` properties of Create method request will be ignored.
   - Property comparison is based on `type` and `name` matching.
   - `oneOf` and `discriminator` definitions must match exactly.
+
 #### 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.
+
 ##### 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 schema to find any properties marked with readOnly attribute
+  - Fails if any readOnly properties are found in the request schema
+
 #### 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.
+
 ##### 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
+
 #### xgen-IPA-106-create-method-response-is-get-method-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
+##### Implementation details
+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
 
 
+
 ### IPA-107
 
 Rule is based on [http://go/ipa/IPA-107](http://go/ipa/IPA-107).
@@ -299,19 +322,48 @@ 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.
+
+##### Implementation details
+Rule checks for the following conditions:
+  - Applies to 204 responses of DELETE methods
+  - Verifies that the response does not contain a schema property
+  - Fails if any content type in the response includes a schema definition
+
 #### xgen-IPA-108-delete-method-return-204-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 DELETE method must return 204 No Content.
+
+##### Implementation details
+Rule checks for the following conditions:
+  - Applies to all DELETE methods
+  - Verifies that the operation includes a 204 response
+  - Ensures there are no other 2xx response codes defined
+  - Fails if 204 is missing or if other 2xx responses exist
+
 #### 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.
+
+##### Implementation details
+Rule checks for the following conditions:
+  - Applies to all DELETE methods
+  - Verifies that the operation includes a 404 response
+  - Fails if the 404 status code is not defined in the responses object
+
 #### xgen-IPA-108-delete-request-no-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
 DELETE method must not have request body.
 
+##### Implementation details
+Rule checks for the following conditions:
+  - Applies to all DELETE methods
+  - Verifies that the operation does not contain a requestBody property
+  - Fails if a requestBody is defined for the DELETE operation
+
+
 
 ### IPA-109
 

From 6749e24a41cdcffbbecfdf522d1f0dbfe0f6b183 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:35:40 +0100
Subject: [PATCH 05/15] IPA-108

---
 tools/spectral/ipa/rulesets/IPA-108.yaml | 86 ++++++++----------------
 1 file changed, 28 insertions(+), 58 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
index 5f32ccb2ad..794755ccd7 100644
--- a/tools/spectral/ipa/rulesets/IPA-108.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -1,70 +1,40 @@
-# IPA-108: Delete
+# IPA-108: Custom Methods
 # http://go/ipa/108
 
-rules:
-  xgen-IPA-108-delete-response-should-be-empty:
-    description: |
-      Delete method response should not have schema reference to object.
-
-      ##### Implementation details
-      Rule checks for the following conditions:
-        - Applies to 204 responses of DELETE methods
-        - Verifies that the response does not contain a schema property
-        - Fails if any content type in the response includes a schema definition
-    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.
-
-      ##### Implementation details
-      Rule checks for the following conditions:
-        - Applies to all DELETE methods
-        - Verifies that the operation includes a 204 response
-        - Ensures there are no other 2xx response codes defined
-        - Fails if 204 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
+functions:
+  - IPA109EachCustomMethodMustBeGetOrPost
+  - IPA109EachCustomMethodMustUseCamelCase
 
-  xgen-IPA-108-delete-include-404-response:
+rules:
+  xgen-IPA-108-custom-method-must-be-GET-or-POST:
     description: |
-      DELETE method must include 404 response and return it when resource not found.
-
+      The HTTP method for custom methods must be GET or POST.
+      
       ##### Implementation details
       Rule checks for the following conditions:
-        - Applies to all DELETE methods
-        - Verifies that the operation includes a 404 response
-        - Fails if the 404 status code is not defined in the responses object
-    message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-include-404-response'
-    severity: warn
-    given: $.paths[*].delete
+        - 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-108-custom-method-must-be-GET-or-POST'
+    severity: error
+    given: '$.paths[*]'
     then:
-      function: IPA108DeleteMethod404Response
+      function: 'IPA109EachCustomMethodMustBeGetOrPost'
 
-  xgen-IPA-108-delete-request-no-body:
+  xgen-IPA-108-custom-method-must-use-camel-case:
     description: |
-      DELETE method must not have request body.
-
+      The custom method must use camelCase format.
+      
       ##### Implementation details
       Rule checks for the following conditions:
-        - Applies to all DELETE methods
-        - Verifies that the operation does not contain a requestBody property
-        - Fails if a requestBody is defined for the DELETE operation
-    message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-request-no-body'
-    severity: warn
-    given: $.paths[*].delete
+        - 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-108-custom-method-must-use-camel-case'
+    severity: error
+    given: '$.paths[*]'
     then:
-      function: IPA108DeleteMethodNoRequestBody
-
-functions:
-  - IPA108DeleteMethodResponseShouldNotHaveSchema
-  - IPA108DeleteMethod204Response
-  - IPA108DeleteMethodNoRequestBody
-  - IPA108DeleteMethod404Response
+      function: 'IPA109EachCustomMethodMustUseCamelCase'

From 970cf2adc962339c2036b4396c75b4e4b13d6c01 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:39:24 +0100
Subject: [PATCH 06/15] IPA-123

---
 tools/spectral/ipa/rulesets/IPA-123.yaml | 10 +++-
 tools/spectral/ipa/rulesets/README.md    | 58 ++++++++++--------------
 2 files changed, 32 insertions(+), 36 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml
index 32e7f81522..86e0ef0218 100644
--- 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
index 5373bd1214..d902e5f90e 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -318,50 +318,30 @@ Validation checks the PATCH method for single resource paths and [singleton reso
 
 Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108).
 
-#### xgen-IPA-108-delete-response-should-be-empty
+#### xgen-IPA-108-custom-method-must-be-GET-or-POST
 
- ![warn](https://img.shields.io/badge/warning-yellow) 
-Delete method response should not have schema reference to object.
-
-##### Implementation details
-Rule checks for the following conditions:
-  - Applies to 204 responses of DELETE methods
-  - Verifies that the response does not contain a schema property
-  - Fails if any content type in the response includes a schema definition
-
-#### xgen-IPA-108-delete-method-return-204-response
-
- ![warn](https://img.shields.io/badge/warning-yellow) 
-DELETE method must return 204 No Content.
-
-##### Implementation details
-Rule checks for the following conditions:
-  - Applies to all DELETE methods
-  - Verifies that the operation includes a 204 response
-  - Ensures there are no other 2xx response codes defined
-  - Fails if 204 is missing or if other 2xx responses exist
-
-#### 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.
+ ![error](https://img.shields.io/badge/error-red) 
+The HTTP method for custom methods must be GET or POST.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies to all DELETE methods
-  - Verifies that the operation includes a 404 response
-  - Fails if the 404 status code is not defined in the responses object
+  - 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
 
-#### xgen-IPA-108-delete-request-no-body
+#### xgen-IPA-108-custom-method-must-use-camel-case
 
- ![warn](https://img.shields.io/badge/warning-yellow) 
-DELETE method must not have request body.
+ ![error](https://img.shields.io/badge/error-red) 
+The custom method must use camelCase format.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies to all DELETE methods
-  - Verifies that the operation does not contain a requestBody property
-  - Fails if a requestBody is defined for the DELETE operation
+  - 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.)
 
 
 
@@ -398,5 +378,13 @@ Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123).
  ![error](https://img.shields.io/badge/error-red) 
 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
+
+
 
 

From e4f3814916884f8303ad4cf6c24082bcdb1b1518 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:40:08 +0100
Subject: [PATCH 07/15] IPA-113

---
 tools/spectral/ipa/rulesets/IPA-113.yaml | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml
index 18703cece1..e3411bc9db 100644
--- 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 successful 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[*]'

From c75b8e7a167bb3ca1a21ee621ee83fd4ee181986 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:40:24 +0100
Subject: [PATCH 08/15] IPA-109

---
 tools/spectral/ipa/rulesets/IPA-109.yaml | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-109.yaml b/tools/spectral/ipa/rulesets/IPA-109.yaml
index f430ed78dc..8ca09e66df 100644
--- a/tools/spectral/ipa/rulesets/IPA-109.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-109.yaml
@@ -7,7 +7,15 @@ 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[*]'
@@ -15,7 +23,16 @@ rules:
       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[*]'

From ef642295ee6db485b35bfc7c9b8b9236e44fea64 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:40:37 +0100
Subject: [PATCH 09/15] fix: minor clarification for 113

---
 tools/spectral/ipa/rulesets/IPA-113.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml
index e3411bc9db..650dee7a85 100644
--- a/tools/spectral/ipa/rulesets/IPA-113.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-113.yaml
@@ -13,7 +13,7 @@ rules:
       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 successful response schemas from the GET method
+        - 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'

From 834a7760442cb3d97bdd47a4a1cba5280bbb4481 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:41:04 +0100
Subject: [PATCH 10/15] fix: lint and regenerate docs

---
 tools/spectral/ipa/rulesets/IPA-105.yaml |  6 +--
 tools/spectral/ipa/rulesets/IPA-108.yaml | 69 ++++++++++++------------
 tools/spectral/ipa/rulesets/IPA-109.yaml |  4 +-
 tools/spectral/ipa/rulesets/IPA-113.yaml |  2 +-
 tools/spectral/ipa/rulesets/IPA-123.yaml |  2 +-
 tools/spectral/ipa/rulesets/README.md    | 26 +++++++++
 6 files changed, 68 insertions(+), 41 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml
index 67ee1ed360..0b9fa89599 100644
--- a/tools/spectral/ipa/rulesets/IPA-105.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-105.yaml
@@ -11,7 +11,7 @@ rules:
   xgen-IPA-105-list-method-response-code-is-200:
     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
@@ -26,7 +26,7 @@ rules:
   xgen-IPA-105-list-method-no-request-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
@@ -40,7 +40,7 @@ rules:
   xgen-IPA-105-resource-has-list:
     description: |
       APIs must provide a List method for resources.
-      
+
       ##### Implementation details
       Rule checks for the following conditions:
         - Applies only to resource collection paths
diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
index 794755ccd7..750e85ae29 100644
--- a/tools/spectral/ipa/rulesets/IPA-108.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -1,40 +1,41 @@
-# IPA-108: Custom Methods
+# IPA-108: Delete
 # http://go/ipa/108
 
-functions:
-  - IPA109EachCustomMethodMustBeGetOrPost
-  - IPA109EachCustomMethodMustUseCamelCase
-
 rules:
-  xgen-IPA-108-custom-method-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-108-custom-method-must-be-GET-or-POST'
-    severity: error
-    given: '$.paths[*]'
+  xgen-IPA-108-delete-response-should-be-empty:
+    description: Delete method response should not have schema reference to object.
+    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.
+    message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-108-delete-method-return-204-response'
+    severity: warn
+    given: $.paths[*].delete
     then:
-      function: 'IPA109EachCustomMethodMustBeGetOrPost'
+      function: IPA108DeleteMethod204Response
 
-  xgen-IPA-108-custom-method-must-use-camel-case:
-    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-108-custom-method-must-use-camel-case'
-    severity: error
-    given: '$.paths[*]'
+  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: 'IPA109EachCustomMethodMustUseCamelCase'
+      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: IPA108DeleteMethodNoRequestBody
+
+functions:
+  - IPA108DeleteMethodResponseShouldNotHaveSchema
+  - IPA108DeleteMethod204Response
+  - IPA108DeleteMethodNoRequestBody
+  - IPA108DeleteMethod404Response
diff --git a/tools/spectral/ipa/rulesets/IPA-109.yaml b/tools/spectral/ipa/rulesets/IPA-109.yaml
index 8ca09e66df..ad7668ebcc 100644
--- a/tools/spectral/ipa/rulesets/IPA-109.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-109.yaml
@@ -9,7 +9,7 @@ rules:
   xgen-IPA-109-custom-method-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)
@@ -25,7 +25,7 @@ rules:
   xgen-IPA-109-custom-method-must-use-camel-case:
     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)
diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml
index 650dee7a85..fd54f81db6 100644
--- a/tools/spectral/ipa/rulesets/IPA-113.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-113.yaml
@@ -8,7 +8,7 @@ rules:
   xgen-IPA-113-singleton-must-not-have-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
diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml
index 86e0ef0218..e8635ed9ab 100644
--- a/tools/spectral/ipa/rulesets/IPA-123.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-123.yaml
@@ -8,7 +8,7 @@ rules:
   xgen-IPA-123-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
diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
index d902e5f90e..8fae2fd4cf 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -353,11 +353,28 @@ 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.
+
+##### 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
+
 #### xgen-IPA-109-custom-method-must-use-camel-case
 
  ![error](https://img.shields.io/badge/error-red) 
 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.)
+
+
 
 ### IPA-113
 
@@ -368,6 +385,15 @@ Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113).
  ![warn](https://img.shields.io/badge/warning-yellow) 
 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
+
+
 
 ### IPA-123
 

From 9db89a3a32ed4b26bb58edc836fffd610e920c2e Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Fri, 14 Mar 2025 20:57:07 +0100
Subject: [PATCH 11/15] fix: IPA-108

---
 tools/spectral/ipa/rulesets/IPA-108.yaml | 37 ++++++++++++++++--
 tools/spectral/ipa/rulesets/README.md    | 50 +++++++++++++++++-------
 2 files changed, 68 insertions(+), 19 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
index 750e85ae29..37adca71f1 100644
--- a/tools/spectral/ipa/rulesets/IPA-108.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -3,7 +3,14 @@
 
 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]
@@ -11,7 +18,15 @@ rules:
       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 that the method includes a 204 response 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
@@ -19,7 +34,14 @@ rules:
       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
@@ -27,7 +49,14 @@ rules:
       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/README.md b/tools/spectral/ipa/rulesets/README.md
index 8fae2fd4cf..c4eb9ca1e2 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -318,30 +318,50 @@ Validation checks the PATCH method for single resource paths and [singleton reso
 
 Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108).
 
-#### xgen-IPA-108-custom-method-must-be-GET-or-POST
+#### xgen-IPA-108-delete-response-should-be-empty
 
- ![error](https://img.shields.io/badge/error-red) 
-The HTTP method for custom methods must be GET or POST.
+ ![warn](https://img.shields.io/badge/warning-yellow) 
+Delete method response should not have schema reference to object.
 
 ##### 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
+  - 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
 
-#### xgen-IPA-108-custom-method-must-use-camel-case
+#### xgen-IPA-108-delete-method-return-204-response
 
- ![error](https://img.shields.io/badge/error-red) 
-The custom method must use camelCase format.
+ ![warn](https://img.shields.io/badge/warning-yellow) 
+DELETE method must return 204 No Content.
 
 ##### 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.)
+  - Applies to all DELETE methods
+  - Verifies that the method includes a 204 response code
+  - Ensures no other 2xx response codes are defined
+  - Fails if the 204 status code is missing or if other 2xx responses exist
+
+#### 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.
+
+##### 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
+
+#### xgen-IPA-108-delete-request-no-body
+
+ ![warn](https://img.shields.io/badge/warning-yellow) 
+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
 
 
 

From 668bdca8c3c2ba39ca47caff8f80f8c8ed5274c1 Mon Sep 17 00:00:00 2001
From: Wojciech Trocki <w.trocki@mongodb.com>
Date: Tue, 18 Mar 2025 12:47:13 +0100
Subject: [PATCH 12/15] Lovisa comments

Co-authored-by: Yeliz Henden <165907936+yelizhenden-mdb@users.noreply.github.com>
Co-authored-by: Lovisa Berggren <59226031+lovisaberggren@users.noreply.github.com>
---
 tools/spectral/ipa/rulesets/IPA-105.yaml |  1 +
 tools/spectral/ipa/rulesets/IPA-106.yaml |  2 +-
 tools/spectral/ipa/rulesets/README.md    | 26 ++++++++++++------------
 3 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml
index 0b9fa89599..2dcf1c802f 100644
--- a/tools/spectral/ipa/rulesets/IPA-105.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-105.yaml
@@ -65,6 +65,7 @@ rules:
         - 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'
     severity: warn
diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml
index 1de05b4562..10474055ca 100644
--- a/tools/spectral/ipa/rulesets/IPA-106.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-106.yaml
@@ -68,7 +68,7 @@ rules:
       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 schema to find any properties marked with readOnly attribute
+        - 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
diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
index c4eb9ca1e2..9f88eec2e1 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -189,8 +189,8 @@ The response body of the List method should consist of the same resource object
   - 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
+  - Verifies that the schema of items in the 'results' array is the same schema used in the Get method response
+  - Fails if the Get method doesn't have a schema reference or if the methods don't reference the same schema
   - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation
 
 
@@ -205,7 +205,7 @@ The Create method request should be a Request suffixed object.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources)
+  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
   - Applies only to JSON content types
   - Verifies the schema references a predefined schema (not inline)
   - Confirms the referenced schema name ends with "Request" suffix
@@ -217,9 +217,9 @@ Create operations should not use query parameters.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources)
+  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
   - Verifies the operation does not contain query parameters
-  - Ignores specified parameters like 'pretty' and 'envelope' via configuration
+  - Ignores specified parameters `pretty` and `envelope` via configuration
 
 #### xgen-IPA-106-create-method-request-body-is-get-method-response
 
@@ -242,10 +242,10 @@ Create method Request object must not include fields with readOnly:true.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources)
+  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
   - Applies only to JSON content types
-  - Searches through the schema to find any properties marked with readOnly attribute
-  - Fails if any readOnly properties are found in the request schema
+  - Searches through the schema to find any properties marked with `readOnly` attribute
+  - Fails if any `readOnly` properties are found in the request schema
 
 #### xgen-IPA-106-create-method-response-code-is-201
 
@@ -254,7 +254,7 @@ Create methods must return a 201 Created response code.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources)
+  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
   - Verifies the 201 Created response code is present
   - Fails if the method lacks a 201 Created response or defines a different 2xx status code
 
@@ -332,7 +332,7 @@ Rule checks for the following conditions:
 #### xgen-IPA-108-delete-method-return-204-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
-DELETE method must return 204 No Content.
+Delete methods must return 204 No Content.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -344,7 +344,7 @@ Rule checks for the following conditions:
 #### 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.
+Delete methods must include 404 response and return it when resource not found.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -355,7 +355,7 @@ Rule checks for the following conditions:
 #### xgen-IPA-108-delete-request-no-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
-DELETE method must not have request body.
+Delete methods must not have request body.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -410,7 +410,7 @@ 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
+  - Verifies that no schema contains `id` or `_id` properties in their object definitions
   - Fails if any response schema contains these identifier properties
 
 

From 96fc6ae1821db340f7cf6821bbd3e0148bc9b5f8 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Tue, 18 Mar 2025 13:07:48 +0100
Subject: [PATCH 13/15] fix: format

---
 tools/spectral/ipa/rulesets/README.md | 27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
index 9f88eec2e1..f7766ce3f0 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -189,8 +189,9 @@ The response body of the List method should consist of the same resource object
   - 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 is the same schema used in the Get method response
-  - Fails if the Get method doesn't have a schema reference or if the methods don't reference the same schema
+  - 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
 
 
@@ -205,7 +206,7 @@ The Create method request should be a Request suffixed object.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
+  - 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
@@ -217,9 +218,9 @@ Create operations should not use query parameters.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
+  - Applies only to POST methods on resource collection paths (non-singleton resources)
   - Verifies the operation does not contain query parameters
-  - Ignores specified parameters `pretty` and `envelope` via configuration
+  - Ignores specified parameters like 'pretty' and 'envelope' via configuration
 
 #### xgen-IPA-106-create-method-request-body-is-get-method-response
 
@@ -242,10 +243,10 @@ Create method Request object must not include fields with readOnly:true.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
+  - Applies only to POST methods on resource collection paths (non-singleton resources)
   - Applies only to JSON content types
-  - Searches through the schema to find any properties marked with `readOnly` attribute
-  - Fails if any `readOnly` properties are found in the request schema
+  - Searches through the request schema to find any properties marked with readOnly attribute
+  - Fails if any readOnly properties are found in the request schema
 
 #### xgen-IPA-106-create-method-response-code-is-201
 
@@ -254,7 +255,7 @@ Create methods must return a 201 Created response code.
 
 ##### Implementation details
 Rule checks for the following conditions:
-  - Applies only to POST methods on resource collection paths (non-singleton resources and non-custom methods)
+  - 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
 
@@ -332,7 +333,7 @@ Rule checks for the following conditions:
 #### xgen-IPA-108-delete-method-return-204-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
-Delete methods must return 204 No Content.
+DELETE method must return 204 No Content.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -344,7 +345,7 @@ Rule checks for the following conditions:
 #### xgen-IPA-108-delete-include-404-response
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
-Delete methods must include 404 response and return it when resource not found.
+DELETE method must include 404 response and return it when resource not found.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -355,7 +356,7 @@ Rule checks for the following conditions:
 #### xgen-IPA-108-delete-request-no-body
 
  ![warn](https://img.shields.io/badge/warning-yellow) 
-Delete methods must not have request body.
+DELETE method must not have request body.
 
 ##### Implementation details
 Rule checks for the following conditions:
@@ -410,7 +411,7 @@ 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
+  - Verifies that no schema contains 'id' or '_id' properties in their object definitions
   - Fails if any response schema contains these identifier properties
 
 

From 138f98f11cbc12d12a87f28917ef3af5c7806199 Mon Sep 17 00:00:00 2001
From: Wojciech Trocki <w.trocki@mongodb.com>
Date: Tue, 18 Mar 2025 13:11:09 +0100
Subject: [PATCH 14/15] Update tools/spectral/ipa/rulesets/IPA-108.yaml

Co-authored-by: Yeliz Henden <165907936+yelizhenden-mdb@users.noreply.github.com>
---
 tools/spectral/ipa/rulesets/IPA-108.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml
index 37adca71f1..21ef005df0 100644
--- a/tools/spectral/ipa/rulesets/IPA-108.yaml
+++ b/tools/spectral/ipa/rulesets/IPA-108.yaml
@@ -24,7 +24,8 @@ rules:
       ##### Implementation details
       Rule checks for the following conditions:
         - Applies to all DELETE methods
-        - Verifies that the method includes a 204 response code
+         - 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'

From 3e258712e68425f29d3ec855be44ccc15154c406 Mon Sep 17 00:00:00 2001
From: wtrocki <w.trocki@mongodb.com>
Date: Tue, 18 Mar 2025 13:11:39 +0100
Subject: [PATCH 15/15] fix: regenerate documentation

---
 tools/spectral/ipa/rulesets/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md
index f7766ce3f0..e9f519d5e1 100644
--- a/tools/spectral/ipa/rulesets/README.md
+++ b/tools/spectral/ipa/rulesets/README.md
@@ -338,7 +338,8 @@ DELETE method must return 204 No Content.
 ##### Implementation details
 Rule checks for the following conditions:
   - Applies to all DELETE methods
-  - Verifies that the method includes a 204 response code
+   - 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