IPA Validation

The IPA validation uses Spectral to validate the MongoDB Atlas Admin API OpenAPI Specification. The rules cover MongoDB's Improvement Proposal for APIs (IPA), which are best-practices for API design.

Quick Links

| Site | Link |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| MongoDB API Standards (IPA) | https://mongodb.github.io/ipa/ |
| Installation & Usage | IPA README |
| Implemented Rules | Ruleset Documentation |
| Spectral Docs | Spectral |
| Contributing | CONTRIBUTING.md |
| Changelog | CHANGELOG.md |
| Issues | https://github.com/mongodb/openapi/issues |

Running Locally

$3

- Node.js >= v20
- npm

$3

To run the IPA validation locally, install necessary dependencies with npm install if you haven't already. Then (from /openapi/tools/spectral/ipa/metrics/scripts/), simply run:

``
npm run ipa-validation
`

This command will run Spectral CLI for the ruleset ipa-spectral.yaml on the raw v2.yaml OpenAPI spec and generate ipa-collector-results-combined.log.

Integrating IPA Validations

To incorporate the IPA Spectral ruleset for OpenAPI specification validation in your repositories, you can follow these implementation approaches:

$3

#### Package-based Installation
Run:
`
npm install @mongodb-js/ipa-validation-ruleset
`

#### Limitations
The IPA Validation Framework uses third party dependencies for certain rules. With this approach, server based installation is not supported. Instead, use the recommended package-based installation or clone the repo.

$3

#### Local Configuration

Create a .spectral.yaml file that extends our ruleset:

`
extends:
- "@mongodb/ipa-validation-ruleset"
`

For more information about how to extend rulesets, see the web page.

#### Customization Options

You can override specific rules from our ruleset by adding them to your local .spectral.yaml:

`
extends:
- "@mongodb/ipa-validation-ruleset"

overrides:
- files:
'**#/components/schemas/ExampleSchema'
'**#/paths/example-path'
rules:
x-xgen-IPA-xxx-rule: 'off'
`

$3

#### GitHub Actions Example

If you use GitHub Actions, you can define a workflow step to include IPA validation, such as

`
- name: IPA validation action
run: npx spectral lint --ruleset=
`

or

`
- name: IPA validation - Spectral GitHub action
uses: stoplightio/spectral-action@2ad0b9302e32a77c1caccf474a9b2191a8060d83
with:
file_glob:
spectral_ruleset:
`

is the ruleset file which extends the IPA Spectral ruleset.

For more information about Spectral GitHub action, see the GitHub repo.

#### Shell Script Example

You can create a validation script similar to this:

`bash
#!/bin/bash
spectral lint --ruleset=
if [ $? -ne 0 ]; then
echo "API validation failed"
exit 1
fi
`

For more information on Spectral CLI, see the web page.

#### Bazel Target Example

You can create a Bazel target using the shell script similar to:

`
sh_binary(
name = "ipa_validation",
srcs = ["ipa_validation.sh"],
data = [
":spectral",
":spectral_config",
],
deps = [
"@bazel_tools//tools/bash/runfiles",
],
)
``