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

Prerequisites

• Node.js >= v20
• npm

Run Validation

To run the IPA validation locally, install necessary dependencies with npm install if you haven't already. Then, 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.

Integrating IPA Validations

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

Installation Options

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.

Integration Methods

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'

CI/CD Integration

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 <openapi-spec-file> --ruleset=<spectral-ruleset-file>

or

    - name: IPA validation - Spectral GitHub action
      uses: stoplightio/spectral-action@2ad0b9302e32a77c1caccf474a9b2191a8060d83
      with:
        file_glob: <openapi-spec-file>
        spectral_ruleset: <spectral-ruleset-file>

<spectral-ruleset-file> 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:

#!/bin/bash
spectral lint <openapi-spec-file> --ruleset=<spectral-ruleset-file>
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",
],
)