oas-validator review
oas-validator 5.0.8 checks an already parsed JavaScript object against OpenAPI 3.0.x structure and OAS-Kit's rule code. The async `validate()` path can resolve references first, then records context, warnings, operation IDs, scope data, metadata, and a `valid` flag on the caller's options object. Structural checks use assertions and stop at the first failure; optional linting can gather several rule violations. Version 5.0.8 changes no validator source from 5.0.7. It only raises `oas-resolver` from `^2.5.5` to `^2.5.6` and `reftools` from `^1.1.8` to `^1.1.9`.
oas-validator 5.0.8 installed as 35 packages using 4 MB and failed our browser bundle check, while its source accepts OpenAPI 3.0.x only. Keep it for an established OAS-Kit server pipeline; choose a current validator for new projects or any OpenAPI 3.1 document.
We installed it
| Install | ✓ · 3.7s | 35 packages on disk · 4 MB |
| Import | ✓ | ESM import works · require() works · CommonJS package |
| Browser | n/a | could not be bundled for the browser (Node-only code, most likely) |
| Types | — | no TypeScript types found |
| Known vulns | 0 | 0 critical · 0 high · 0 moderate · 0 low (npm audit) |
Answers from our run
Does oas-validator install cleanly?
Yes. In a fresh container with an empty cache, npm install oas-validator finished in 4 seconds, leaving 35 packages and 4 MB on disk. npm audit reported no known vulnerabilities.
Can oas-validator run in a browser?
Not directly: esbuild could not bundle it for the browser in our run, which normally means it depends on Node built-ins. Use it on the server, or find a browser-targeted alternative.
Does oas-validator work with both ESM and CommonJS?
Yes. Both import 'oas-validator' and require('oas-validator') worked in Node 22 in our run. The package is published as CommonJS.
Does oas-validator include TypeScript types?
No type declarations were found in our install, so TypeScript users need their own declarations.
oas-validator or @apidevtools/swagger-parser: which should you use?
@apidevtools/swagger-parser: Use it when parsing, resolving, dereferencing, and validating Swagger 2.0 or OpenAPI 3.0 should come from one maintained package. oas-validator 5.0.8 installed as 35 packages using 4 MB and failed our browser bundle check, while its source accepts OpenAPI 3.0.x only.
When should you not use oas-validator?
Any input uses OpenAPI 3.1. Version 5.0.8 explicitly requires the version string to begin with 3.0..
Use it if
- An existing OAS-Kit pipeline already shares resolver, linter, cache, handler, and options conventions with oas-validator.
- Every accepted document declares OpenAPI 3.0.x and one structural error at a time is enough for the caller.
- Legacy CommonJS code needs both Promise and Node-style callback forms from the same validation function.
- Reference resolution is required and your application can restrict files, URL schemes, hosts, and fetch timeouts.
- Any input uses OpenAPI 3.1. Version 5.0.8 explicitly requires the version string to begin with `3.0.`.
- A CI report must list every structural problem in one pass. Assertion checks reject at the first error; multiple results apply only to lint warnings.
- A browser-side validator is required. Our esbuild browser build failed, and the package pulls Node-oriented resolver and filesystem code.
- Typed ESM imports are a requirement. The 2021 package is CommonJS with no declarations and no exports map.
- A small validation-only dependency is expected. Our install left 35 packages, while the manifest declares 8 direct dependencies including a resolver, linter, schema walker, YAML parser, and assertion library.
Setup reality
Our clean Node 22 install of oas-validator 5.0.8 finished in 3.7 seconds. It left 35 packages and 4 MB on disk; the package itself was 80 KB unpacked. npm audit reported 0 known vulnerabilities. The manifest declares 8 direct dependencies, no peers, and a BSD-3-Clause license. CommonJS require() and ESM import both worked in our sandbox, but the package includes no TypeScript declarations or exports map. esbuild could not produce a browser bundle.
Pass a parsed object and a mutable options object. oas-validator does not open your top-level JSON or YAML file for you. validate(document, options) resolves with that same options object after setting fields such as valid, context, warnings, operationIds, openapi, cache, and metadata. A third callback argument replaces the returned Promise. On failure, the rejected error carries error.options; the last context entry is usually the useful JSON Pointer. Structural validation deliberately stops after 1 error.
Reference resolution is optional and changes the threat model. Set resolve: true plus source when relative $ref values need a base. The resolver options accept custom fetch logic, fetch options, agents, cache objects, and protocol handlers. Uploaded specifications can therefore cause file or network reads unless the caller restricts schemes, paths, hosts, redirects, response sizes, and timeouts. Internal references are checked during ordinary validation, while external resources need the resolver path.
OpenAPI support stops at 3.0.x even though the npm description says 3.x. Lint mode loads OAS-Kit's default rules, appends results to options.warnings, and rejects if any warnings remain; lintLimit controls display count rather than acceptance. The 5.0.8 patch only updates 2 resolver-related ranges, so it adds no OpenAPI 3.1 model or typing layer. Keep this on server or CLI code, pin the dependency tree, and regression-test error context if an existing OAS-Kit workflow depends on it.
Patterns
Validate a parsed OpenAPI object validate-object
const validator = require('oas-validator');
const options = {};
try {
const result = await validator.validate(document, options);
console.log(result.valid);
} catch (error) {
console.error(error.message);
}The Promise resolves to the mutated options object with `valid: true`; it does not return a new OpenAPI document.
Read JSON before validation parse-json-file
const fs = require('node:fs/promises');
const validator = require('oas-validator');
const text = await fs.readFile('./openapi.json', 'utf8');
const document = JSON.parse(text);
const options = {source: './openapi.json', text};
await validator.validate(document, options);`source` gives relative references a base, while `text` lets the validator record an input line count in metadata.
Convert YAML text into an object first parse-yaml-file
const fs = require('node:fs/promises');
const YAML = require('yaml');
const validator = require('oas-validator');
const text = await fs.readFile('./openapi.yaml', 'utf8');
const document = YAML.parse(text);
await validator.validate(document, {source: './openapi.yaml', text});oas-validator 5.0.8 accepts a JavaScript object; the caller owns top-level file I/O and YAML parsing.
Print the failing JSON Pointer report-first-error
const options = {};
try {
await validator.validate(document, options);
} catch (error) {
const context = error.options?.context ?? options.context ?? [];
console.error(error.message);
console.error(context.at(-1) ?? '#/');
}Structural checks stop after 1 error, and the final context entry is the nearest location retained when that assertion failed.
Validate through a Node-style callback use-callback-api
validator.validate(document, {}, (error, options) => {
if (error) {
console.error(error.message);
return;
}
console.log(options.valid);
});Supplying the third argument switches delivery to the callback instead of returning the validation Promise.
Apply bundled lint rules run-default-linter
const options = {lint: true, lintLimit: 20};
try {
await validator.validate(document, options);
} catch (error) {
for (const warning of options.warnings) {
console.error(warning.pointer, warning.rule?.name);
}
}Lint mode can collect several warnings, but 1 or more remaining warnings causes validation to reject.
Disable named OAS-Kit lint checks skip-lint-rules
const options = {
lint: true,
lintLimit: 50,
lintSkip: ['operation-tags', 'info-contact'],
};
await validator.validate(document, options);Rule names come from the installed `oas-linter` 3.x dependency, so pin the lockfile before treating skips as policy.
Resolve external files from a known base resolve-relative-refs
const options = {
resolve: true,
source: '/srv/specs/openapi.yaml',
cache: {},
};
await validator.validate(document, options);`resolve: true` may read external locations referenced by the document; restrict uploaded specs to an allowed directory.
Allow reference fetches from one host restrict-remote-refs
const options = {
resolve: true,
source: 'https://specs.example.com/openapi.yaml',
fetch: async (url, init) => {
const target = new URL(url);
if (target.hostname !== 'specs.example.com') {
throw new Error('reference host blocked');
}
return fetch(target, {
...init,
signal: AbortSignal.timeout(5_000),
});
},
};
await validator.validate(document, options);A custom fetch must still enforce redirect, address, response-size, and 5-second timeout policy for untrusted references.
Check the four required top-level values preflight-document-shape
if (!validator.microValidate(document, {})) {
throw new Error('missing openapi, info title/version, or paths');
}
await validator.validate(document, {});`microValidate()` checks only `openapi`, `info.title`, `info.version`, and `paths`; it is not OpenAPI conformance validation.
Permit an existing default/type mismatch relax-default-types
await validator.validate(document, {
laxDefaults: true,
});`laxDefaults` disables a schema consistency check; use it only for a known compatibility exception rather than as a default setting.
Fail early on an unsupported spec version reject-openapi-31
if (!String(document.openapi).startsWith('3.0.')) {
throw new Error('oas-validator 5.0.8 accepts OpenAPI 3.0.x only');
}
await validator.validate(document, {});Version 5.0.8 asserts the same `3.0.` prefix internally; route OpenAPI 3.1 documents to another validator.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| @apidevtools/swagger-parser | npm | Use it when parsing, resolving, dereferencing, and validating Swagger 2.0 or OpenAPI 3.0 should come from one maintained package. |
| openapi-schema-validator | npm | Use it when direct document schema validation fits better than OAS-Kit's mutable options pipeline. |
| @redocly/openapi-core | npm | Use it when validation belongs with Redocly's bundling, lint rules, and wider OpenAPI toolchain. |
| ibm-openapi-validator | npm | Use it when configurable lint policy and a fuller governance report are the main goals. |
More utils guides
lru-cache · ajv · type-fest · p-limit · find-up · js-yaml · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.