diff --git a/tools/spectral/ipa/__tests__/exceptionExtensionFormat.test.js b/tools/spectral/ipa/__tests__/IPA105exceptionExtensionFormat.test.js similarity index 92% rename from tools/spectral/ipa/__tests__/exceptionExtensionFormat.test.js rename to tools/spectral/ipa/__tests__/IPA105exceptionExtensionFormat.test.js index 2f39e0565c..5264f037bc 100644 --- a/tools/spectral/ipa/__tests__/exceptionExtensionFormat.test.js +++ b/tools/spectral/ipa/__tests__/IPA105exceptionExtensionFormat.test.js @@ -51,25 +51,25 @@ testRule('xgen-IPA-005-exception-extension-format', [ errors: [ { code: 'xgen-IPA-005-exception-extension-format', - message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5', + message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102', path: ['paths', '/path1', 'x-xgen-IPA-exception'], severity: DiagnosticSeverity.Warning, }, { code: 'xgen-IPA-005-exception-extension-format', - message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5', + message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102', path: ['paths', '/path2', 'x-xgen-IPA-exception', 'xgen-IPA-100-rule-name'], severity: DiagnosticSeverity.Warning, }, { code: 'xgen-IPA-005-exception-extension-format', - message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5', + message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102', path: ['paths', '/path3', 'x-xgen-IPA-exception', 'invalid-rule-name'], severity: DiagnosticSeverity.Warning, }, { code: 'xgen-IPA-005-exception-extension-format', - message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa/5', + message: 'IPA exceptions must have a valid rule name and a reason. http://go/ipa-spectral#IPA-102', path: ['paths', '/path4', 'x-xgen-IPA-exception', 'xgen-IPA-100-rule-name'], severity: DiagnosticSeverity.Warning, }, diff --git a/tools/spectral/ipa/rulesets/IPA-005.yaml b/tools/spectral/ipa/rulesets/IPA-005.yaml index f3637dcfdc..5bdc7710e1 100644 --- a/tools/spectral/ipa/rulesets/IPA-005.yaml +++ b/tools/spectral/ipa/rulesets/IPA-005.yaml @@ -2,13 +2,20 @@ # http://go/ipa/5 functions: - - exceptionExtensionFormat + - IPA105ExceptionExtensionFormat rules: xgen-IPA-005-exception-extension-format: - description: 'IPA exception extensions must follow the correct format. http://go/ipa/5' - message: '{{error}} http://go/ipa/5' + description: | + IPA exception extensions must follow the correct format. http://go/ipa/5 + + ##### Implementation details + Rule checks for the following conditions: + - Exception rule names must start with 'xgen-IPA-' prefix + - Each exception must include a non-empty reason as a string + - This rule itself does not allow exceptions + message: '{{error}} http://go/ipa-spectral#IPA-102' severity: error given: '$..x-xgen-IPA-exception' then: - function: 'exceptionExtensionFormat' + function: 'IPA105ExceptionExtensionFormat' diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index ec0f038b34..6070ce942b 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -17,6 +17,12 @@ Rule is based on [http://go/ipa/IPA-5](http://go/ipa/IPA-5). ![error](https://img.shields.io/badge/error-red) IPA exception extensions must follow the correct format. http://go/ipa/5 +##### Implementation details +Rule checks for the following conditions: + - Exception rule names must start with 'xgen-IPA-' prefix + - Each exception must include a non-empty reason as a string + - This rule itself does not allow exceptions + ### IPA-102 @@ -27,7 +33,6 @@ Rule is based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102). ![error](https://img.shields.io/badge/error-red) Paths should alternate between resource names and path params. http://go/ipa/102 - #### xgen-IPA-102-collection-identifier-camelCase ![warn](https://img.shields.io/badge/warning-yellow) @@ -44,14 +49,12 @@ Collection identifiers must be in camelCase. - Paths with `x-xgen-IPA-exception` for this rule are excluded from validation - Double slashes (//) are not allowed in paths - #### xgen-IPA-102-collection-identifier-pattern ![warn](https://img.shields.io/badge/warning-yellow) Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers. http://go/ipa/102 - ### IPA-104 Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104). @@ -60,34 +63,28 @@ Rule is based on [http://go/ipa/IPA-104](http://go/ipa/IPA-104). ![warn](https://img.shields.io/badge/warning-yellow) APIs must provide a Get method for resources. http://go/ipa/104 - #### xgen-IPA-104-get-method-returns-single-resource ![warn](https://img.shields.io/badge/warning-yellow) The purpose of the Get method is to return data from a single resource. http://go/ipa/104 - #### xgen-IPA-104-get-method-response-code-is-200 ![warn](https://img.shields.io/badge/warning-yellow) The Get method must return a 200 OK response. http://go/ipa/104 - #### xgen-IPA-104-get-method-returns-response-suffixed-object ![warn](https://img.shields.io/badge/warning-yellow) The Get method of a resource should return a "Response" suffixed object. http://go/ipa/104 - #### xgen-IPA-104-get-method-response-has-no-input-fields ![warn](https://img.shields.io/badge/warning-yellow) The Get method response object must not include writeOnly properties (fields that should be used only on creation or update, ie output fields). http://go/ipa/104 - #### xgen-IPA-104-get-method-no-request-body ![warn](https://img.shields.io/badge/warning-yellow) The Get method request must not include a body. http://go/ipa/104 - ### IPA-105 Rule is based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105). @@ -96,19 +93,16 @@ Rule is based on [http://go/ipa/IPA-105](http://go/ipa/IPA-105). ![warn](https://img.shields.io/badge/warning-yellow) The List method must return a 200 OK response. http://go/ipa/105 - #### xgen-IPA-105-list-method-no-request-body ![warn](https://img.shields.io/badge/warning-yellow) The List method request must not include a body. http://go/ipa/105 - #### xgen-IPA-105-resource-has-list ![warn](https://img.shields.io/badge/warning-yellow) APIs must provide a List method for resources. http://go/ipa/105 - ### IPA-106 Rule is based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106). @@ -117,29 +111,24 @@ Rule is based on [http://go/ipa/IPA-106](http://go/ipa/IPA-106). ![warn](https://img.shields.io/badge/warning-yellow) The Create method request should be a Request suffixed object. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. - #### xgen-IPA-106-create-method-should-not-have-query-parameters ![warn](https://img.shields.io/badge/warning-yellow) Create operations should not use query parameters. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. - #### xgen-IPA-106-create-method-request-body-is-get-method-response ![warn](https://img.shields.io/badge/warning-yellow) Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly/writeOnly properties will be ignored. This rule applies only to POST requests targeting resource collection URIs. - #### xgen-IPA-106-create-method-request-has-no-readonly-fields ![warn](https://img.shields.io/badge/warning-yellow) Create method Request object must not include fields with readOnly:true. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. - #### xgen-IPA-106-create-method-response-code-is-201 ![warn](https://img.shields.io/badge/warning-yellow) Create methods must return a 201 Created response code. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. - ### IPA-108 Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108). @@ -148,24 +137,20 @@ Rule is based on [http://go/ipa/IPA-108](http://go/ipa/IPA-108). ![warn](https://img.shields.io/badge/warning-yellow) Delete method response should not have schema reference to object. http://go/ipa/108 - #### xgen-IPA-108-delete-method-return-204-response ![warn](https://img.shields.io/badge/warning-yellow) DELETE method must return 204 No Content. http://go/ipa/108 - #### xgen-IPA-108-delete-include-404-response ![warn](https://img.shields.io/badge/warning-yellow) DELETE method must include 404 response and return it when resource not found. http://go/ipa/108 - #### xgen-IPA-108-delete-request-no-body ![warn](https://img.shields.io/badge/warning-yellow) DELETE method must not have request body. http://go/ipa/108 - ### IPA-109 Rule is based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109). @@ -174,14 +159,12 @@ Rule is based on [http://go/ipa/IPA-109](http://go/ipa/IPA-109). ![error](https://img.shields.io/badge/error-red) The HTTP method for custom methods must be GET or POST. http://go/ipa/109 - #### xgen-IPA-109-custom-method-must-use-camel-case ![error](https://img.shields.io/badge/error-red) The custom method must use camelCase format. http://go/ipa/109 - ### IPA-113 Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113). @@ -192,7 +175,6 @@ Rule is based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113). Singleton resources must not have a user-provided or system-generated ID. http://go/ipa/113 - ### IPA-123 Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123). @@ -204,4 +186,3 @@ Enum values must be UPPER_SNAKE_CASE. http://go/ipa/123 - diff --git a/tools/spectral/ipa/rulesets/functions/exceptionExtensionFormat.js b/tools/spectral/ipa/rulesets/functions/IPA105ExceptionExtensionFormat.js similarity index 100% rename from tools/spectral/ipa/rulesets/functions/exceptionExtensionFormat.js rename to tools/spectral/ipa/rulesets/functions/IPA105ExceptionExtensionFormat.js diff --git a/tools/spectral/ipa/scripts/generateRulesetReadme.js b/tools/spectral/ipa/scripts/generateRulesetReadme.js index 3dd588e557..5565d53690 100644 --- a/tools/spectral/ipa/scripts/generateRulesetReadme.js +++ b/tools/spectral/ipa/scripts/generateRulesetReadme.js @@ -60,7 +60,7 @@ function generateRulesetSections(rules) { sortedRuleEntries.forEach((rule) => { const severityFormatted = formatSeverity(rule.severity); - sections += `#### ${rule.name}\n\n ${severityFormatted} \n${rule.description}\n\n`; + sections += `#### ${rule.name}\n\n ${severityFormatted} \n${rule.description}\n`; }); return sections;