IBM openapi-validator checks OpenAPI documents against IBM best practices, and defers to Spectral when you have it

A linter for OpenAPI 3.0.x and 3.1.x with a rule set you did not write

The IBM OpenAPI Validator lets you validate OpenAPI 3.0.x and OpenAPI 3.1.x documents for compliance with the OpenAPI specifications, as well as IBM-defined best practices. The validator analyzes your API definition and reports any problems within it.

The tool is highly customizable, and it supports a number of rules from Spectral. You can extend the tool with custom rules to meet your specific needs and ensure compliance to your standards. That framing matters: this is not a schema checker with a fixed rule table, it is a linter whose rule set is data, and the data has a default and a well defined override path.

The primary language is JavaScript, and the repository is a monorepo with npm workspaces. The package.json declares three of them:

  "name": "ibm-openapi-validator",
  "workspaces": [
    "packages/utilities",
    "packages/ruleset",
    "packages/validator"
  ],

So the ruleset, the utilities, and the validator itself are separate publishable pieces, and the naming follows the package layout in the repository. That split is why the ruleset can be consumed on its own.

Prerequisites are Node 16.0.0+ and NPM 8.3.0+, which are old floors for a tool published in 2026 and worth checking against your own toolchain constraints before you plan an upgrade.

A Spectral file in your repo quietly wins over the IBM defaults

This is the behaviour to understand before anything else. By default, the validator uses the IBM Cloud Validation Ruleset, which ships as the npm package @ibm-cloud/openapi-ruleset.

However, if the validator detects the presence of any of the standard Spectral ruleset files, meaning .spectral.yaml, .spectral.yml, .spectral.json, or .spectral.js, in the current directory from which the validator is being run, or in any containing directory within the file system, then that ruleset file will be used instead.

Two consequences follow. First, the override is directory based and walks upwards, so a ruleset file anywhere above your project directory changes the behaviour of the validator for your project. Second, the override is silent. There is no flag to pass and no configuration to set, and the tool does not need to be told, because it looks for these files itself.

If you want the IBM rules back while a Spectral file is present, you can force it with -r default or --ruleset default, or by setting the ruleset configuration property to the value 'default'. To point at a specific custom ruleset file, use -r or --ruleset with the name of your file.

So there are three states to be aware of in practice: the IBM rules by default, your own ruleset file discovered automatically, and the IBM rules explicitly restored with -r default. In a repository that already uses Spectral, the middle state is what you get whether or not you intended it.

Installing with npm, a platform binary, or the container image

There are three ways to install the validator: using NPM, downloading a platform-specific binary, or building from source.

The recommended route is npm, and the command is npm install -g ibm-openapi-validator. The -g flag installs the tool globally so the validator can be run from anywhere in the file system. Alternatively, you can pass no flag or the --save-dev flag to add the validator as a dependency to your project and run it from your NPM scripts or JavaScript code. That second option is the one to pick in CI, where a global install is usually not what you want.

Platform-specific binary files are packaged with each release for MacOS, Linux, and Windows, and those do not depend on Node.JS being installed. That is the escape hatch for a locked down build environment where a global npm install is not permitted.

Building from source is a four step sequence: clone or download the repository, navigate to the root directory, install the dependencies using npm install, and build the command line tool by running npm run link. If you previously installed the validator globally with npm install -g ibm-openapi-validator, you need to run npm uninstall -g ibm-openapi-validator before running npm run link, otherwise the two copies collide.

You can also build standalone binaries with npm run pkg, which produces lint-openapi-macos, lint-openapi-linux, and lint-openapi-windows.exe in the project's packages/validator/bin directory.

The container image mounts your definition read only and defaults to the latest tag

The container image runs the validator with your API definition mounted in. If the file is named openapi.yaml in the current directory:

docker run \
  --rm --tty \
  --volume "$PWD:/data:ro" \
  ibmdevxsdk/openapi-validator:latest \
    openapi.yaml

The volume is mounted read only and the working directory inside the image is /data, so flag and argument syntax is the same as described in the usage section, but file paths are relative to /data.

The project states that you should replace latest with a specific tagged version to avoid any surprises when new releases are published. That advice is worth following literally. A lint gate that silently changes behaviour when a new image is pushed is exactly the kind of pipeline surprise nobody wants to debug on a Friday, and the fix is a single tag in the command.

To use a custom ruleset named ruleset.yaml in the current directory, the same run command takes an extra flag:

docker run \
  --rm --tty \
  --volume "$PWD:/data:ro" \
  ibmdevxsdk/openapi-validator:latest \
    --ruleset ruleset.yaml \
    openapi.yaml

The image is built from a node:18-alpine base, copies the package manifests first so dependency installation can be cached, sets NODE_PATH so the IBM ruleset can be found from volume mounts and ruleset extensions, and finishes with a link step that puts the validator on the executable path as lint-openapi. The package.json also carries a build-docker script and a test-docker script that exercise the image against a mock definition, which tells you the container path is tested rather than aspirational.

Configuration properties for output, severity and files

The behaviour of the tool is controlled through named configuration properties rather than only through flags, and and the same property names apply in programmatic use.

The list is visible in the project's own table of contents: colorizeOutput, errorsOnly, files, ignoreFiles, limits, logLevels, outputFormat, ruleset, summaryOnly, produceImpactScore, and markdownReport.

Several of these are worth pausing on. errorsOnly and summaryOnly are both about how much you see, and they pull in opposite directions: one suppresses everything that is not an error, the other suppresses everything except a summary. outputFormat and markdownReport together decide the shape of the report you paste into a pull request. produceImpactScore is a scoring output rather than a pass or fail, which suits a dashboard over a gate. files and ignoreFiles control what is scanned. logLevels controls verbosity.

Because the same names appear as configuration properties and as command line options, and the ruleset property duplicates the -r flag, the tool can be driven the same way from a config file, from a shell, and from code.

Programmatic use, output formats, and the logging model

Beyond the command line, the validator can be used programmatically, and the project guide covers both Text and JSON output, with additional customization described for the text output.

Two output paths serve two different consumers. Text is for a human reading a terminal or a log, and it is the format that supports further customization. JSON is for a program, a CI annotation step, or a dashboard that wants to count problems by rule rather than by regex over coloured lines. The JSON output is the one to pick if you want to fail a build on a specific rule identifier.

The logging model is separate from the report output, which is a distinction worth keeping straight. logLevels controls how much the tool says while it works, and outputFormat controls what the tool produces as its result. Turning up log levels will not make the report more detailed, and switching to JSON will not make the tool more verbose. Teams that conflate the two end up either with unreadable logs or an unreadable report.

The repository also carries an AGENTS.md file at the top level, along with CHANGELOG.md, Migration-Guide.md, and a renovate.json for dependency updates, which are signs of a project that has to be navigated by people and tools other than its original authors.

Release cadence, the ruleset as a separate package, and licence

The project ships three related packages in step with each other. On 2026-09-18 the validator released [email protected], the ruleset released @ibm-cloud/[email protected], and the utilities released @ibm-cloud/[email protected].

The fact that the ruleset is a separate package with its own version is the single most important maintenance detail for anyone depending on it. Your application pins a validator version, but the rules it enforces come from a different package that can move on its own schedule. If you need reproducible results across a team, pin the ruleset explicitly rather than relying on the default the validator happens to pull in.

The last push to the repository was on 2026-10-15, so the work is current, and the release process is automated through semantic-release, which means patch versions in the changelog correspond to fixes and minor versions correspond to behaviour changes. There is a Migration-Guide.md in the repository, so major version bumps come with notes on how to move.

The repository is licensed Apache-2.0, and the container image labels itself with the same licence. Apache-2.0 is permissive and carries an explicit patent grant, which suits a linter that most teams will run in a build pipeline rather than ship as part of a product. Read the LICENSE file for the exact terms.

What the project does not promise is equally relevant. There is no claim about how many rules exist, no benchmark on large definitions, and no list of which best practice rules are errors versus warnings in every configuration. If you need a specific rule to be a hard failure in CI, verify its severity in the ruleset you are actually running rather than assuming.

Editorial conclusion

The IBM OpenAPI Validator fits API teams that publish cloud style definitions and want a lint gate that encodes IBM rules without hand writing them, and it fits existing Spectral users because an existing .spectral.yaml is picked up automatically. It does not fit teams who need only spec conformance, since the IBM best practice rules add opinion beyond the OpenAPI specification. Before adding it to a pipeline, check whether a Spectral ruleset file already exists in your repository, since that file will override the IBM Cloud Validation Ruleset unless you pass -r default.

Frequently asked questions

Official sources

1. IBM/openapi-validator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases