Registry / http-networking / oas-validator

oas-validator

library5.0.8jsnpmunverified

oas-validator is a JavaScript library designed for parsing and validating OpenAPI 3.x definitions. The current stable version is 5.0.8. It operates as an assertion-based validator, meaning it ceases validation upon encountering the first structural error, which is crucial for preventing a cascade of spurious errors. However, it also offers a 'lint' option to report multiple warnings for non-critical issues. Key differentiators include its internal use of `reftools` for JSON Pointer and Reference resolution, a transition from older implementations like `jgeXml`. The library supports both Promise-based and callback-based asynchronous usage patterns, catering to different integration preferences. Its primary use case is ensuring the correctness and adherence to the OpenAPI specification of API definitions, often integrated into CI/CD pipelines or development tooling.

http-networking testing serialization

npm install oas-validator

github ↗package ↗

INSTALL

IMPORT

SIG · OAS-VALIDATOR

oas-validator

http-networkingjavascriptv5.0.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

validator (ESM)

✓ import validator from 'oas-validator'; // Then use validator.validate(openapi, options);

✗ import { validate } from 'oas-validator';

For ESM, the module exports a default object containing the `validate` method. Direct named import of `validate` is incorrect.

validator (CJS)

✓ const validator = require('oas-validator'); // Then use validator.validate(openapi, options);

✗ import validator from 'oas-validator'; // In CommonJS files

This is the documented CommonJS usage. Ensure your environment is configured for CommonJS modules when using `require()`.

ValidationOptions (Type)

✓ import type { Options as ValidationOptions } from 'oas-validator';

✗ import { Options } from 'oas-validator';

The primary `Options` type for configuring validation parameters should be imported using `import type` to avoid runtime dependencies.

This quickstart demonstrates how to import and use `oas-validator` with an OpenAPI 3.x definition, showcasing the Promise-based API and basic error handling.

import validator from 'oas-validator'; const openapiDefinition = { openapi: '3.0.0', info: { title: 'Sample API', version: '1.0.0', }, paths: { '/hello': { get: { summary: 'Says hello', responses: { '200': { description: 'A greeting', content: { 'text/plain': { schema: { type: 'string' } } } } } } } } }; const options = {}; // No linting, stops on first error validator.validate(openapiDefinition, options) .then(function(result){ if (result.valid) { console.log('OpenAPI definition is valid.'); } else { // This branch is rarely hit for critical errors due to assertion-based validation console.warn('OpenAPI definition has warnings or soft errors:', result.warnings); } }) .catch(function(err){ console.error('Validation error caught:', err.message); if (err.context) console.error('Location:', err.context.pop()); });

Debug

Known issues

gotchaBy default, `oas-validator` is an assertion-based validator that stops on the first structural error encountered. This means it will not report all errors in a document, only the first critical one.

fix

To receive multiple non-critical warnings (e.g., linting issues), set the `lint` option to `true` in the validation options object (e.g., `{ lint: true }`). Critical structural errors will still halt validation immediately.

affects: >=2.0.0

breakingVersion 2.10.0 (or a preceding major version) migrated from `jgeXml` to `reftools` for JSON Pointer and Reference implementation. While generally an improvement, this might lead to subtle changes in how references are resolved or edge cases handled compared to older versions.

fix

Thoroughly test existing OpenAPI definitions after upgrading from versions predating the `reftools` integration to ensure no unexpected changes in validation behavior. Review `reftools` documentation if encountering specific reference resolution issues.

affects: >=2.10.0

gotchaThe `validate` function supports both Promise-based and callback-based interfaces. Providing a third `callback` argument will trigger the callback mode, preventing a Promise from being returned. Mixing these patterns can lead to unexpected behavior.

fix

Consistently use either the Promise-based approach (`.then().catch()`) or the callback approach, but not both simultaneously. For modern async JavaScript, the Promise-based interface is generally recommended.

affects: >=2.0.0

gotchaThe provided README examples show CommonJS `require()`. While `oas-validator` supports ESM, directly `import { validate } from 'oas-validator'` is incorrect, as the main export is a default object containing the `validate` method.

fix

For ESM, use `import validator from 'oas-validator';` and then call `validator.validate(...)`. Ensure your project configuration (e.g., `package.json` `type` field) is set appropriately for ESM if using Node.js modules.

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: validator.validate is not a function

Incorrect import statement for ESM. You are likely attempting to named import `validate` instead of default importing the validator object.

fix

Change `import { validate } from 'oas-validator';` to `import validator from 'oas-validator';` and then use `validator.validate(...)`.

Validation error caught: Structural error at /paths/~1invalidPath

The OpenAPI definition contains a structural error (e.g., a missing required field or malformed path) that violates the OpenAPI 3.x specification. `oas-validator` stopped on this first critical error.

fix

Inspect the reported `Location` in the error context to identify and correct the specific part of your OpenAPI definition that is invalid. For a broader range of non-critical warnings, enable the `lint: true` option.

SyntaxError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax in an ECMAScript module (ESM) environment (e.g., a `.js` file with `"type": "module"` in `package.json` or a `.mjs` file).

fix

Convert `const validator = require('oas-validator');` to `import validator from 'oas-validator';`. Ensure your module is properly configured for ESM.

Upgrade

Version history

5.0.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Mermade/oas-kit ↗

packagehttps://www.npmjs.com/package/oas-validator ↗