{"id":48815,"library":"oav","title":"oav: Azure OpenAPI Validation Tools","description":"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.","status":"active","version":"4.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/azure/oav","tags":["javascript","typescript"],"install":[{"cmd":"npm install oav","lang":"bash","label":"npm"},{"cmd":"yarn add oav","lang":"bash","label":"yarn"},{"cmd":"pnpm add oav","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v4. Use named import. CommonJS require still works but not recommended.","wrong":"const validateSpec = require('oav').validateSpec","symbol":"validateSpec","correct":"import { validateSpec } from 'oav'"},{"note":"Import from 'oav' root, not subpath. The lib is bundled.","wrong":"import { validateExamples } from 'oav/lib'","symbol":"validateExamples","correct":"import { validateExamples } from 'oav'"},{"note":"Named export, not default. Ensure TypeScript strict mode for proper type inference.","wrong":"const oav = require('oav'); oav.validateTraffic(...)","symbol":"validateTraffic","correct":"import { validateTraffic } from 'oav'"}],"quickstart":{"code":"import { validateSpec, validateExamples } from 'oav';\n\nasync function main() {\n  const specPath = './specification/compute/resource-manager/Microsoft.Compute/stable/2021-07-01/compute.json';\n  // Validate spec semantic\n  const specErrors = await validateSpec(specPath, { consoleLogLevel: 'error' });\n  console.log('Spec validation errors:', specErrors.length);\n  // Validate examples against spec\n  const exampleErrors = await validateExamples(specPath, { consoleLogLevel: 'error' });\n  console.log('Example validation errors:', exampleErrors.length);\n}\nmain().catch(console.error);","lang":"typescript","description":"Validates an Azure OpenAPI spec and its x-ms-examples using async API. Shows import pattern and basic usage."},"warnings":[{"fix":"Switch to import syntax or use dynamic import() in CommonJS modules.","message":"oav v4 drops CommonJS support. Require() will fail unless using Node.js ESM interop.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade Node.js to v18 or higher.","message":"Node.js 18 is minimum required. Older Node versions are unsupported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use JavaScript/TypeScript API instead of CLI for spec validation.","message":"`validate-spec` CLI command is deprecated in favor of programmatic `validateSpec` API.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Use path.resolve() or path.join(__dirname, ...) for Linux compatibility.","message":"File paths must be absolute or relative to CWD. Symbolic links may cause resolution errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use JSON.stringify with custom replacer or utility library for logging.","message":"Validation errors are returned as arrays but may include non-serializable objects. Stringify carefully.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'18':86 '2.0':25 '4.0.4':31 'api':20 'azur':2,18,38,67,79,98 'built':64 'cadenc':33 'check':63 'ci/cd':95 'cli':13 'conform':69 'current':28 'differenti':43 'driven':36 'exampl':55,61,75 'format':27 'integr':77 'javascript':101 'key':42 'librari':15 'model':51 'ms':74 'need':41 'node.js':85 'oav':1,6 'openapi':3,8,24 'openapi-validation-tool':7 'period':35 'pipelin':96 'primarili':92 'provid':45 'proxi':82 'qualiti':62 'record':59,83 'releas':32 'repo':100 'request/response':54 'requir':84 'rest':19 'sdk':39,99 'semant':46 'ship':87 'spec':49,68 'specif':21,65 'stabl':29 'structur':50 'support':71 'swagger':26 'test':81 'test-proxi':80 'tool':5,10,40 'traffic':56 'type':89 'typescript':88,102 'use':93 'valid':4,9,17,47,52,57 'version':30 'written':22 'x':73 'x-ms-exampl':72","created_at":"2026-06-07T16:58:36.710571+00:00","updated_at":"2026-06-07T16:58:36.710571+00:00","problems":[{"fix":"Run 'npm install oav' in your project directory (not globally for programmatic use).","cause":"Package not installed or installed globally instead of locally.","error":"Error: Cannot find module 'oav'"},{"fix":"Use import { validateSpec } from 'oav' instead of import oav from 'oav'.","cause":"Using default import instead of named import in ESM.","error":"TypeError: oav.validateSpec is not a function"},{"fix":"Add \"type\": \"module\" in package.json or use .mjs extension. Or use dynamic import() inside CommonJS.","cause":"Running ESM code in CommonJS context without proper configuration.","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Upgrade Node.js to v18 or later (e.g., via nvm).","cause":"Node.js version too old.","error":"Error: Unsupported node version. Required >=18.x"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/azure/oav","github":"https://github.com/azure/oav","docs":null,"changelog":null,"pypi":null,"npm":"oav","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}