oav

library4.0.4jsnpmunverified

oav (openapi-validation-tools) is a CLI and library for validating Azure REST API specifications written in OpenAPI 2.0 (Swagger) format. Current stable version: 4.0.4. Release cadence is periodic, driven by Azure SDK tooling needs. Key differentiators: it provides semantic validation of spec structures, model validation for request/response examples, traffic validation against recordings, and example quality checks. Built specifically for Azure spec conformance, it supports x-ms-examples and integrates with Azure test-proxy recordings. Requires Node.js >=18, ships TypeScript types, and is primarily used in CI/CD pipelines for Azure SDK repos.

testing devops

npm install oav

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OAV

oav

testingjavascriptv4.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

validateSpec

✓ import { validateSpec } from 'oav'

✗ const validateSpec = require('oav').validateSpec

ESM-only since v4. Use named import. CommonJS require still works but not recommended.

validateExamples

✓ import { validateExamples } from 'oav'

✗ import { validateExamples } from 'oav/lib'

Import from 'oav' root, not subpath. The lib is bundled.

validateTraffic

✓ import { validateTraffic } from 'oav'

✗ const oav = require('oav'); oav.validateTraffic(...)

Named export, not default. Ensure TypeScript strict mode for proper type inference.

Validates an Azure OpenAPI spec and its x-ms-examples using async API. Shows import pattern and basic usage.

import { validateSpec, validateExamples } from 'oav'; async function main() { const specPath = './specification/compute/resource-manager/Microsoft.Compute/stable/2021-07-01/compute.json'; // Validate spec semantic const specErrors = await validateSpec(specPath, { consoleLogLevel: 'error' }); console.log('Spec validation errors:', specErrors.length); // Validate examples against spec const exampleErrors = await validateExamples(specPath, { consoleLogLevel: 'error' }); console.log('Example validation errors:', exampleErrors.length); } main().catch(console.error);

Debug

Known issues

breakingoav v4 drops CommonJS support. Require() will fail unless using Node.js ESM interop.

fix

Switch to import syntax or use dynamic import() in CommonJS modules.

affects: >=4.0.0

breakingNode.js 18 is minimum required. Older Node versions are unsupported.

fix

Upgrade Node.js to v18 or higher.

affects: >=4.0.0

deprecated`validate-spec` CLI command is deprecated in favor of programmatic `validateSpec` API.

fix

Use JavaScript/TypeScript API instead of CLI for spec validation.

affects: >=4.0.0

gotchaFile paths must be absolute or relative to CWD. Symbolic links may cause resolution errors.

fix

Use path.resolve() or path.join(__dirname, ...) for Linux compatibility.

affects: >=1.0.0

gotchaValidation errors are returned as arrays but may include non-serializable objects. Stringify carefully.

fix

Use JSON.stringify with custom replacer or utility library for logging.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'oav'

Package not installed or installed globally instead of locally.

fix

Run 'npm install oav' in your project directory (not globally for programmatic use).

TypeError: oav.validateSpec is not a function

Using default import instead of named import in ESM.

fix

Use import { validateSpec } from 'oav' instead of import oav from 'oav'.

SyntaxError: Unexpected token 'export'

Running ESM code in CommonJS context without proper configuration.

fix

Add "type": "module" in package.json or use .mjs extension. Or use dynamic import() inside CommonJS.

Error: Unsupported node version. Required >=18.x

Node.js version too old.

fix

Upgrade Node.js to v18 or later (e.g., via nvm).

Upgrade

Version history

4.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/azure/oav ↗

packageoav ↗

homepagehttps://github.com/azure/oav ↗