diff --git a/tools/spectral/ipa/__tests__/collectionIdentifierCamelCase.test.js b/tools/spectral/ipa/__tests__/IPA102CollectionIdentifierCamelCase.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/collectionIdentifierCamelCase.test.js rename to tools/spectral/ipa/__tests__/IPA102CollectionIdentifierCamelCase.test.js diff --git a/tools/spectral/ipa/__tests__/collectionIdentifierPattern.test.js b/tools/spectral/ipa/__tests__/IPA102CollectionIdentifierPattern.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/collectionIdentifierPattern.test.js rename to tools/spectral/ipa/__tests__/IPA102CollectionIdentifierPattern.test.js diff --git a/tools/spectral/ipa/__tests__/eachPathAlternatesBetweenResourceNameAndPathParam.test.js b/tools/spectral/ipa/__tests__/IPA102EachPathAlternatesBetweenResourceNameAndPathParam.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachPathAlternatesBetweenResourceNameAndPathParam.test.js rename to tools/spectral/ipa/__tests__/IPA102EachPathAlternatesBetweenResourceNameAndPathParam.test.js diff --git a/tools/spectral/ipa/__tests__/eachResourceHasGetMethod.test.js b/tools/spectral/ipa/__tests__/IPA104EachResourceHasGetMethod.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachResourceHasGetMethod.test.js rename to tools/spectral/ipa/__tests__/IPA104EachResourceHasGetMethod.test.js diff --git a/tools/spectral/ipa/__tests__/getMethodHasNoRequestBody.test.js b/tools/spectral/ipa/__tests__/IPA104GetMethodHasNoRequestBody.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/getMethodHasNoRequestBody.test.js rename to tools/spectral/ipa/__tests__/IPA104GetMethodHasNoRequestBody.test.js diff --git a/tools/spectral/ipa/__tests__/getMethodResponseHasNoInputFields.test.js b/tools/spectral/ipa/__tests__/IPA104GetMethodResponseHasNoInputFields.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/getMethodResponseHasNoInputFields.test.js rename to tools/spectral/ipa/__tests__/IPA104GetMethodResponseHasNoInputFields.test.js diff --git a/tools/spectral/ipa/__tests__/getMethodReturnsResponseSuffixedObject.test.js b/tools/spectral/ipa/__tests__/IPA104GetMethodReturnsResponseSuffixedObject.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/getMethodReturnsResponseSuffixedObject.test.js rename to tools/spectral/ipa/__tests__/IPA104GetMethodReturnsResponseSuffixedObject.test.js diff --git a/tools/spectral/ipa/__tests__/getMethodReturnsSingleResource.test.js b/tools/spectral/ipa/__tests__/IPA104GetMethodReturnsSingleResource.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/getMethodReturnsSingleResource.test.js rename to tools/spectral/ipa/__tests__/IPA104GetMethodReturnsSingleResource.test.js diff --git a/tools/spectral/ipa/__tests__/getResponseCodeShouldBe200OK.test.js b/tools/spectral/ipa/__tests__/IPA104GetResponseCodeShouldBe200OK.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/getResponseCodeShouldBe200OK.test.js rename to tools/spectral/ipa/__tests__/IPA104GetResponseCodeShouldBe200OK.test.js diff --git a/tools/spectral/ipa/__tests__/eachResourceHasListMethod.test.js b/tools/spectral/ipa/__tests__/IPA105EachResourceHasListMethod.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachResourceHasListMethod.test.js rename to tools/spectral/ipa/__tests__/IPA105EachResourceHasListMethod.test.js diff --git a/tools/spectral/ipa/__tests__/listMethodHasNoRequestBody.test.js b/tools/spectral/ipa/__tests__/IPA105ListMethodHasNoRequestBody.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/listMethodHasNoRequestBody.test.js rename to tools/spectral/ipa/__tests__/IPA105ListMethodHasNoRequestBody.test.js diff --git a/tools/spectral/ipa/__tests__/listMethodResponseIsGetMethodResponse.test.js b/tools/spectral/ipa/__tests__/IPA105ListMethodResponseIsGetMethodResponse.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/listMethodResponseIsGetMethodResponse.test.js rename to tools/spectral/ipa/__tests__/IPA105ListMethodResponseIsGetMethodResponse.test.js diff --git a/tools/spectral/ipa/__tests__/listResponseCodeShouldBe200OK.test.js b/tools/spectral/ipa/__tests__/IPA105ListResponseCodeShouldBe200OK.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/listResponseCodeShouldBe200OK.test.js rename to tools/spectral/ipa/__tests__/IPA105ListResponseCodeShouldBe200OK.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodRequestBodyIsGetResponse.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodRequestBodyIsGetResponse.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodRequestBodyIsGetResponse.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodRequestBodyIsGetResponse.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodRequestBodyIsRequestSuffixedObject.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodRequestBodyIsRequestSuffixedObject.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodRequestBodyIsRequestSuffixedObject.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodRequestBodyIsRequestSuffixedObject.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodRequestHasNoReadonlyFields.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodRequestHasNoReadonlyFields.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodRequestHasNoReadonlyFields.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodRequestHasNoReadonlyFields.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodResponseCodeIs201Created.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodResponseCodeIs201Created.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodResponseCodeIs201Created.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodResponseCodeIs201Created.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodResponseIsGetMethodResponse.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodResponseIsGetMethodResponse.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodResponseIsGetMethodResponse.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodResponseIsGetMethodResponse.test.js diff --git a/tools/spectral/ipa/__tests__/createMethodShouldNotHaveQueryParameters.test.js b/tools/spectral/ipa/__tests__/IPA106CreateMethodShouldNotHaveQueryParameters.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/createMethodShouldNotHaveQueryParameters.test.js rename to tools/spectral/ipa/__tests__/IPA106CreateMethodShouldNotHaveQueryParameters.test.js diff --git a/tools/spectral/ipa/__tests__/updateMethodMustNotHaveQueryParams.test.js b/tools/spectral/ipa/__tests__/IPA107UpdateMethodMustNotHaveQueryParams.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/updateMethodMustNotHaveQueryParams.test.js rename to tools/spectral/ipa/__tests__/IPA107UpdateMethodMustNotHaveQueryParams.test.js diff --git a/tools/spectral/ipa/__tests__/updateResponseCodeShouldBe200OK.test.js b/tools/spectral/ipa/__tests__/IPA107UpdateResponseCodeShouldBe200OK.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/updateResponseCodeShouldBe200OK.test.js rename to tools/spectral/ipa/__tests__/IPA107UpdateResponseCodeShouldBe200OK.test.js diff --git a/tools/spectral/ipa/__tests__/deleteMethod204Response.test.js b/tools/spectral/ipa/__tests__/IPA108DeleteMethod204Response.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/deleteMethod204Response.test.js rename to tools/spectral/ipa/__tests__/IPA108DeleteMethod204Response.test.js diff --git a/tools/spectral/ipa/__tests__/deleteMethod404Response.test.js b/tools/spectral/ipa/__tests__/IPA108DeleteMethod404Response.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/deleteMethod404Response.test.js rename to tools/spectral/ipa/__tests__/IPA108DeleteMethod404Response.test.js diff --git a/tools/spectral/ipa/__tests__/deleteMethodNoRequestBody.test.js b/tools/spectral/ipa/__tests__/IPA108DeleteMethodNoRequestBody.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/deleteMethodNoRequestBody.test.js rename to tools/spectral/ipa/__tests__/IPA108DeleteMethodNoRequestBody.test.js diff --git a/tools/spectral/ipa/__tests__/deleteMethodResponseShouldNotHaveSchema.test.js b/tools/spectral/ipa/__tests__/IPA108DeleteMethodResponseShouldNotHaveSchema.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/deleteMethodResponseShouldNotHaveSchema.test.js rename to tools/spectral/ipa/__tests__/IPA108DeleteMethodResponseShouldNotHaveSchema.test.js diff --git a/tools/spectral/ipa/__tests__/eachCustomMethodMustBeGetOrPost.test.js b/tools/spectral/ipa/__tests__/IPA109EachCustomMethodMustBeGetOrPost.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachCustomMethodMustBeGetOrPost.test.js rename to tools/spectral/ipa/__tests__/IPA109EachCustomMethodMustBeGetOrPost.test.js diff --git a/tools/spectral/ipa/__tests__/eachCustomMethodMustUseCamelCase.test.js b/tools/spectral/ipa/__tests__/IPA109EachCustomMethodMustUseCamelCase.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachCustomMethodMustUseCamelCase.test.js rename to tools/spectral/ipa/__tests__/IPA109EachCustomMethodMustUseCamelCase.test.js diff --git a/tools/spectral/ipa/__tests__/singletonHasNoId.test.js b/tools/spectral/ipa/__tests__/IPA113SingletonHasNoId.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/singletonHasNoId.test.js rename to tools/spectral/ipa/__tests__/IPA113SingletonHasNoId.test.js diff --git a/tools/spectral/ipa/__tests__/eachEnumValueMustBeUpperSnakeCase.test.js b/tools/spectral/ipa/__tests__/IPA123EachEnumValueMustBeUpperSnakeCase.test.js similarity index 100% rename from tools/spectral/ipa/__tests__/eachEnumValueMustBeUpperSnakeCase.test.js rename to tools/spectral/ipa/__tests__/IPA123EachEnumValueMustBeUpperSnakeCase.test.js diff --git a/tools/spectral/ipa/rulesets/IPA-102.yaml b/tools/spectral/ipa/rulesets/IPA-102.yaml index b5b860e3cb..358cd73801 100644 --- a/tools/spectral/ipa/rulesets/IPA-102.yaml +++ b/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 diff --git a/tools/spectral/ipa/rulesets/IPA-104.yaml b/tools/spectral/ipa/rulesets/IPA-104.yaml index 1a24ec9001..c50a092d6a 100644 --- a/tools/spectral/ipa/rulesets/IPA-104.yaml +++ b/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' diff --git a/tools/spectral/ipa/rulesets/IPA-105.yaml b/tools/spectral/ipa/rulesets/IPA-105.yaml index 26fc3d7b1f..db004218a0 100644 --- a/tools/spectral/ipa/rulesets/IPA-105.yaml +++ b/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,14 +14,14 @@ 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' @@ -29,7 +29,7 @@ rules: 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' diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml index 1f3239787c..1f674a35cc 100644 --- a/tools/spectral/ipa/rulesets/IPA-106.yaml +++ b/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' diff --git a/tools/spectral/ipa/rulesets/IPA-107.yaml b/tools/spectral/ipa/rulesets/IPA-107.yaml index 896ee78f64..92661d29c5 100644 --- a/tools/spectral/ipa/rulesets/IPA-107.yaml +++ b/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' diff --git a/tools/spectral/ipa/rulesets/IPA-108.yaml b/tools/spectral/ipa/rulesets/IPA-108.yaml index 9a20af4f91..750e85ae29 100644 --- a/tools/spectral/ipa/rulesets/IPA-108.yaml +++ b/tools/spectral/ipa/rulesets/IPA-108.yaml @@ -8,7 +8,7 @@ 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. @@ -16,7 +16,7 @@ rules: 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. @@ -24,7 +24,7 @@ rules: 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. @@ -32,10 +32,10 @@ rules: severity: warn given: $.paths[*].delete then: - function: deleteMethodNoRequestBody + function: IPA108DeleteMethodNoRequestBody functions: - - deleteMethodResponseShouldNotHaveSchema - - deleteMethod204Response - - deleteMethodNoRequestBody - - deleteMethod404Response + - IPA108DeleteMethodResponseShouldNotHaveSchema + - IPA108DeleteMethod204Response + - IPA108DeleteMethodNoRequestBody + - IPA108DeleteMethod404Response diff --git a/tools/spectral/ipa/rulesets/IPA-109.yaml b/tools/spectral/ipa/rulesets/IPA-109.yaml index 0aaafb77cf..f430ed78dc 100644 --- a/tools/spectral/ipa/rulesets/IPA-109.yaml +++ b/tools/spectral/ipa/rulesets/IPA-109.yaml @@ -2,8 +2,8 @@ # http://go/ipa/109 functions: - - eachCustomMethodMustBeGetOrPost - - eachCustomMethodMustUseCamelCase + - IPA109EachCustomMethodMustBeGetOrPost + - IPA109EachCustomMethodMustUseCamelCase rules: xgen-IPA-109-custom-method-must-be-GET-or-POST: @@ -12,7 +12,7 @@ rules: severity: error given: '$.paths[*]' then: - function: 'eachCustomMethodMustBeGetOrPost' + function: 'IPA109EachCustomMethodMustBeGetOrPost' xgen-IPA-109-custom-method-must-use-camel-case: description: 'The custom method must use camelCase format.' @@ -20,4 +20,4 @@ rules: severity: error given: '$.paths[*]' then: - function: 'eachCustomMethodMustUseCamelCase' + function: 'IPA109EachCustomMethodMustUseCamelCase' diff --git a/tools/spectral/ipa/rulesets/IPA-113.yaml b/tools/spectral/ipa/rulesets/IPA-113.yaml index 3078d4d511..18703cece1 100644 --- a/tools/spectral/ipa/rulesets/IPA-113.yaml +++ b/tools/spectral/ipa/rulesets/IPA-113.yaml @@ -2,7 +2,7 @@ # http://go/ipa/113 functions: - - singletonHasNoId + - IPA113SingletonHasNoId rules: xgen-IPA-113-singleton-must-not-have-id: @@ -11,4 +11,4 @@ rules: severity: warn given: '$.paths[*]' then: - function: 'singletonHasNoId' + function: 'IPA113SingletonHasNoId' diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml index 3464a51cbe..32e7f81522 100644 --- a/tools/spectral/ipa/rulesets/IPA-123.yaml +++ b/tools/spectral/ipa/rulesets/IPA-123.yaml @@ -2,7 +2,7 @@ # http://go/ipa/123 functions: - - eachEnumValueMustBeUpperSnakeCase + - IPA123EachEnumValueMustBeUpperSnakeCase rules: xgen-IPA-123-enum-values-must-be-upper-snake-case: @@ -11,4 +11,4 @@ rules: severity: error given: '$..enum' then: - function: 'eachEnumValueMustBeUpperSnakeCase' + function: 'IPA123EachEnumValueMustBeUpperSnakeCase' diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index d9083a3853..f1e80fea76 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -33,6 +33,15 @@ Rule is based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102). ![error](https://img.shields.io/badge/error-red) Paths should alternate between resource names and path params. + +##### 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 + #### xgen-IPA-102-collection-identifier-camelCase ![warn](https://img.shields.io/badge/warning-yellow) @@ -54,6 +63,16 @@ Collection identifiers must be in camelCase. ![warn](https://img.shields.io/badge/warning-yellow) 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 + + ### IPA-104 @@ -63,27 +82,68 @@ Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104). ![warn](https://img.shields.io/badge/warning-yellow) APIs must provide a Get method for resources. + +##### 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 + #### xgen-IPA-104-get-method-returns-single-resource ![warn](https://img.shields.io/badge/warning-yellow) The purpose of the Get method is to return data from a single resource. + +##### 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 + #### xgen-IPA-104-get-method-response-code-is-200 ![warn](https://img.shields.io/badge/warning-yellow) The Get method must return a 200 OK response. + +##### 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 + #### xgen-IPA-104-get-method-returns-response-suffixed-object ![warn](https://img.shields.io/badge/warning-yellow) The Get method of a resource should return a "Response" suffixed object. + +##### 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 + #### xgen-IPA-104-get-method-response-has-no-input-fields ![warn](https://img.shields.io/badge/warning-yellow) The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields). + +##### 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 + #### xgen-IPA-104-get-method-no-request-body ![warn](https://img.shields.io/badge/warning-yellow) The Get method request must not include a body. +##### 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 + + ### IPA-105 diff --git a/tools/spectral/ipa/rulesets/functions/collectionIdentifierCamelCase.js b/tools/spectral/ipa/rulesets/functions/IPA102CollectionIdentifierCamelCase.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/collectionIdentifierCamelCase.js rename to tools/spectral/ipa/rulesets/functions/IPA102CollectionIdentifierCamelCase.js diff --git a/tools/spectral/ipa/rulesets/functions/collectionIdentifierPattern.js b/tools/spectral/ipa/rulesets/functions/IPA102CollectionIdentifierPattern.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/collectionIdentifierPattern.js rename to tools/spectral/ipa/rulesets/functions/IPA102CollectionIdentifierPattern.js diff --git a/tools/spectral/ipa/rulesets/functions/eachPathAlternatesBetweenResourceNameAndPathParam.js b/tools/spectral/ipa/rulesets/functions/IPA102EachPathAlternatesBetweenResourceNameAndPathParam.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachPathAlternatesBetweenResourceNameAndPathParam.js rename to tools/spectral/ipa/rulesets/functions/IPA102EachPathAlternatesBetweenResourceNameAndPathParam.js diff --git a/tools/spectral/ipa/rulesets/functions/eachResourceHasGetMethod.js b/tools/spectral/ipa/rulesets/functions/IPA104EachResourceHasGetMethod.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachResourceHasGetMethod.js rename to tools/spectral/ipa/rulesets/functions/IPA104EachResourceHasGetMethod.js diff --git a/tools/spectral/ipa/rulesets/functions/getMethodHasNoRequestBody.js b/tools/spectral/ipa/rulesets/functions/IPA104GetMethodHasNoRequestBody.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/getMethodHasNoRequestBody.js rename to tools/spectral/ipa/rulesets/functions/IPA104GetMethodHasNoRequestBody.js diff --git a/tools/spectral/ipa/rulesets/functions/getMethodResponseHasNoInputFields.js b/tools/spectral/ipa/rulesets/functions/IPA104GetMethodResponseHasNoInputFields.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/getMethodResponseHasNoInputFields.js rename to tools/spectral/ipa/rulesets/functions/IPA104GetMethodResponseHasNoInputFields.js diff --git a/tools/spectral/ipa/rulesets/functions/getMethodReturnsResponseSuffixedObject.js b/tools/spectral/ipa/rulesets/functions/IPA104GetMethodReturnsResponseSuffixedObject.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/getMethodReturnsResponseSuffixedObject.js rename to tools/spectral/ipa/rulesets/functions/IPA104GetMethodReturnsResponseSuffixedObject.js diff --git a/tools/spectral/ipa/rulesets/functions/getMethodReturnsSingleResource.js b/tools/spectral/ipa/rulesets/functions/IPA104GetMethodReturnsSingleResource.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/getMethodReturnsSingleResource.js rename to tools/spectral/ipa/rulesets/functions/IPA104GetMethodReturnsSingleResource.js diff --git a/tools/spectral/ipa/rulesets/functions/getResponseCodeShouldBe200OK.js b/tools/spectral/ipa/rulesets/functions/IPA104GetResponseCodeShouldBe200OK.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/getResponseCodeShouldBe200OK.js rename to tools/spectral/ipa/rulesets/functions/IPA104GetResponseCodeShouldBe200OK.js diff --git a/tools/spectral/ipa/rulesets/functions/eachResourceHasListMethod.js b/tools/spectral/ipa/rulesets/functions/IPA105EachResourceHasListMethod.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachResourceHasListMethod.js rename to tools/spectral/ipa/rulesets/functions/IPA105EachResourceHasListMethod.js diff --git a/tools/spectral/ipa/rulesets/functions/listMethodHasNoRequestBody.js b/tools/spectral/ipa/rulesets/functions/IPA105ListMethodHasNoRequestBody.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/listMethodHasNoRequestBody.js rename to tools/spectral/ipa/rulesets/functions/IPA105ListMethodHasNoRequestBody.js diff --git a/tools/spectral/ipa/rulesets/functions/listMethodResponseIsGetMethodResponse.js b/tools/spectral/ipa/rulesets/functions/IPA105ListMethodResponseIsGetMethodResponse.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/listMethodResponseIsGetMethodResponse.js rename to tools/spectral/ipa/rulesets/functions/IPA105ListMethodResponseIsGetMethodResponse.js diff --git a/tools/spectral/ipa/rulesets/functions/listResponseCodeShouldBe200OK.js b/tools/spectral/ipa/rulesets/functions/IPA105ListResponseCodeShouldBe200OK.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/listResponseCodeShouldBe200OK.js rename to tools/spectral/ipa/rulesets/functions/IPA105ListResponseCodeShouldBe200OK.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodRequestBodyIsGetResponse.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestBodyIsGetResponse.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodRequestBodyIsGetResponse.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestBodyIsGetResponse.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodRequestBodyIsRequestSuffixedObject.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestBodyIsRequestSuffixedObject.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodRequestBodyIsRequestSuffixedObject.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestBodyIsRequestSuffixedObject.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodRequestHasNoReadonlyFields.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestHasNoReadonlyFields.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodRequestHasNoReadonlyFields.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodRequestHasNoReadonlyFields.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodResponseCodeIs201Created.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodResponseCodeIs201Created.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodResponseCodeIs201Created.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodResponseCodeIs201Created.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodResponseIsGetMethodResponse.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodResponseIsGetMethodResponse.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodResponseIsGetMethodResponse.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodResponseIsGetMethodResponse.js diff --git a/tools/spectral/ipa/rulesets/functions/createMethodShouldNotHaveQueryParameters.js b/tools/spectral/ipa/rulesets/functions/IPA106CreateMethodShouldNotHaveQueryParameters.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/createMethodShouldNotHaveQueryParameters.js rename to tools/spectral/ipa/rulesets/functions/IPA106CreateMethodShouldNotHaveQueryParameters.js diff --git a/tools/spectral/ipa/rulesets/functions/updateMethodMustNotHaveQueryParams.js b/tools/spectral/ipa/rulesets/functions/IPA107UpdateMethodMustNotHaveQueryParams.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/updateMethodMustNotHaveQueryParams.js rename to tools/spectral/ipa/rulesets/functions/IPA107UpdateMethodMustNotHaveQueryParams.js diff --git a/tools/spectral/ipa/rulesets/functions/updateResponseCodeShouldBe200OK.js b/tools/spectral/ipa/rulesets/functions/IPA107UpdateResponseCodeShouldBe200OK.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/updateResponseCodeShouldBe200OK.js rename to tools/spectral/ipa/rulesets/functions/IPA107UpdateResponseCodeShouldBe200OK.js diff --git a/tools/spectral/ipa/rulesets/functions/deleteMethod204Response.js b/tools/spectral/ipa/rulesets/functions/IPA108DeleteMethod204Response.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/deleteMethod204Response.js rename to tools/spectral/ipa/rulesets/functions/IPA108DeleteMethod204Response.js diff --git a/tools/spectral/ipa/rulesets/functions/deleteMethod404Response.js b/tools/spectral/ipa/rulesets/functions/IPA108DeleteMethod404Response.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/deleteMethod404Response.js rename to tools/spectral/ipa/rulesets/functions/IPA108DeleteMethod404Response.js diff --git a/tools/spectral/ipa/rulesets/functions/deleteMethodNoRequestBody.js b/tools/spectral/ipa/rulesets/functions/IPA108DeleteMethodNoRequestBody.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/deleteMethodNoRequestBody.js rename to tools/spectral/ipa/rulesets/functions/IPA108DeleteMethodNoRequestBody.js diff --git a/tools/spectral/ipa/rulesets/functions/deleteMethodResponseShouldNotHaveSchema.js b/tools/spectral/ipa/rulesets/functions/IPA108DeleteMethodResponseShouldNotHaveSchema.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/deleteMethodResponseShouldNotHaveSchema.js rename to tools/spectral/ipa/rulesets/functions/IPA108DeleteMethodResponseShouldNotHaveSchema.js diff --git a/tools/spectral/ipa/rulesets/functions/eachCustomMethodMustBeGetOrPost.js b/tools/spectral/ipa/rulesets/functions/IPA109EachCustomMethodMustBeGetOrPost.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachCustomMethodMustBeGetOrPost.js rename to tools/spectral/ipa/rulesets/functions/IPA109EachCustomMethodMustBeGetOrPost.js diff --git a/tools/spectral/ipa/rulesets/functions/eachCustomMethodMustUseCamelCase.js b/tools/spectral/ipa/rulesets/functions/IPA109EachCustomMethodMustUseCamelCase.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachCustomMethodMustUseCamelCase.js rename to tools/spectral/ipa/rulesets/functions/IPA109EachCustomMethodMustUseCamelCase.js diff --git a/tools/spectral/ipa/rulesets/functions/singletonHasNoId.js b/tools/spectral/ipa/rulesets/functions/IPA113SingletonHasNoId.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/singletonHasNoId.js rename to tools/spectral/ipa/rulesets/functions/IPA113SingletonHasNoId.js diff --git a/tools/spectral/ipa/rulesets/functions/eachEnumValueMustBeUpperSnakeCase.js b/tools/spectral/ipa/rulesets/functions/IPA123EachEnumValueMustBeUpperSnakeCase.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/eachEnumValueMustBeUpperSnakeCase.js rename to tools/spectral/ipa/rulesets/functions/IPA123EachEnumValueMustBeUpperSnakeCase.js diff --git a/tools/spectral/ipa/rulesets/functions/utils/resourceEvaluation.js b/tools/spectral/ipa/rulesets/functions/utils/resourceEvaluation.js index 98c38d3d8d..9912c9bcc3 100644 --- a/tools/spectral/ipa/rulesets/functions/utils/resourceEvaluation.js +++ b/tools/spectral/ipa/rulesets/functions/utils/resourceEvaluation.js @@ -159,6 +159,7 @@ function resourceBelongsToSingleParent(resourcePath) { return isPathParam(parentResourceSection); } +// TODO move prefixes to be rule arguments function removePrefix(path) { if (path.startsWith(AUTH_PREFIX)) { return path.slice(AUTH_PREFIX.length);