Skip to content

CLOUDP-305862: IPA 106 documentation standard #537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 14, 2025
Merged

CLOUDP-305862: IPA 106 documentation standard #537

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4dce501
CLOUDP-305862: IPA 106 documentation standard
wtrocki Mar 13, 2025
18fbb30
fix: remove redundant line breaks
wtrocki Mar 13, 2025
a8bbdc0
fix: format
wtrocki Mar 13, 2025
dd68576
fix: revert formatting in generator
wtrocki Mar 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions ..._tests__/exceptionExtensionFormat.test.js → ...__/IPA105exceptionExtensionFormat.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
Expand Down
15 changes: 11 additions & 4 deletions tools/spectral/ipa/rulesets/IPA-005.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
87 changes: 21 additions & 66 deletions tools/spectral/ipa/rulesets/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@ 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
Expand All @@ -26,9 +31,7 @@ Rule is based on [http://go/ipa/IPA-102](http://go/ipa/IPA-102).
#### xgen-IPA-102-path-alternate-resource-name-path-param

![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
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)
Collection identifiers must be in camelCase.
Expand All @@ -43,145 +46,101 @@ Collection identifiers must be in camelCase.
argument to the rule
- 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).

#### xgen-IPA-104-resource-has-GET

![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
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
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
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
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
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).

#### xgen-IPA-105-list-method-response-code-is-200

![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
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
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).

#### xgen-IPA-106-create-method-request-body-is-request-suffixed-object

![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
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
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
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
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).

#### xgen-IPA-108-delete-response-should-be-empty

![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
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
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
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).

#### xgen-IPA-109-custom-method-must-be-GET-or-POST

![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
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).
Expand All @@ -191,8 +150,6 @@ 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. http://go/ipa/113



### IPA-123

Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123).
Expand All @@ -203,5 +160,3 @@ Rule is based on [http://go/ipa/IPA-123](http://go/ipa/IPA-123).
Enum values must be UPPER_SNAKE_CASE. http://go/ipa/123




0 ...ets/functions/exceptionExtensionFormat.js → ...nctions/IPA105ExceptionExtensionFormat.js
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion tools/spectral/ipa/scripts/generateRulesetReadme.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}`;
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could not understand ####. Should it represent heading level?
It is appended to the end of the IPA principle link in the documentation. Is it expected behavior?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. It is heading. Best way to understand it IMHO is to look at generated readme that is part of PR

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this is a wrong one
http://go/ipa/102#### xgen-IPA-102-collection-identifier-camelCase but it should be something like

http://go/ipa/102
#### xgen-IPA-102-collection-identifier-camelCase

Copy link
Member Author

@wtrocki wtrocki Mar 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes. I do not wanted to touch other ipas. Will revert that fix and make it as last fix after all docs changes are done

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to fix those in descriptions by changing way we format multi line descriptions :D

});

return sections;
Expand Down
Loading