Skip to content

Commit a5d66dc

Browse files
author
Sophia Marie Terry
committed
docs: update contributing.md with override details
1 parent 813ba03 commit a5d66dc

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

tools/spectral/CONTRIBUTING.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,31 @@ Instead of using the [Spectral overrides approach](https://docs.stoplight.io/doc
3434
"xgen-IPA-104-resource-has-GET": "Legacy API, not used by infrastructure-as-code tooling",
3535
}
3636
```
37+
38+
### Overrides
39+
40+
We also use custom OAS extensions to handle overrides for IPA validation rules for OperationIDs. Override extensions are added to a component to adapt how it is validated against naming guidelines.
41+
42+
#### Verb Override
43+
The verb override is used to alter the default method verb (Get, List, Create, Update, Delete). With the `customMethod` boolean set to true, validation will occur as part of IPA109. It should be set to false to differentiate between `Get` and `List` methods.
44+
```
45+
"x-xgen-method-verb-override": {
46+
"verb": "{custom verb}",
47+
"customMethod" : <bool>
48+
}
49+
```
50+
51+
#### Length Override
52+
The length override is used internally to reconcile lengthy OperationID in downstream tooling. The chosen override value must:
53+
1. Begin with the default or overridden verb
54+
2. Have a length of 4 words (the verb + 3 nouns)
55+
3. Have only nouns that appear in the resource path
56+
4. End with the last noun in the resource path
57+
58+
When the override is required, a recommended override will be provided. If overrides are required frequently but OperationIDs are not required for your tooling, it is advisable to disable OperationID validation.
59+
```
60+
{ "x-xgen-operation-id-override": "myOperationID" }
61+
```
3762
---
3863
## Testing
3964

@@ -73,6 +98,7 @@ npx prettier . --write
7398

7499
```
75100
npm run gen-ipa-docs
101+
npm run gen-ipa-changelog
76102
```
77103

78104
- [ ] Reference related issues (e.g., Closes #123)

0 commit comments

Comments
 (0)