{"_id":"@platformatic/openapi-schema-validator","_rev":"6-4bb8b61be0d3a6db7b16fa0cc68afef8","name":"@platformatic/openapi-schema-validator","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@platformatic/openapi-schema-validator","version":"3.0.0","keywords":["openapi","json","schema","validation"],"author":{"url":"https://platformatic.dev","name":"Platformatic Inc.","email":"oss@platformatic.dev"},"license":"MIT","_id":"@platformatic/openapi-schema-validator@3.0.0","maintainers":[{"name":"qard","email":"admin@stephenbelanger.com"},{"name":"shogun_panda","email":"paolo@cowtech.it"},{"name":"antoniosonis","email":"anthonysonis@gmail.com"},{"name":"mzugm","email":"mzugm@1368435.ca"},{"name":"leorossi","email":"leonardo.rossi@gmail.com"},{"name":"marcopiraccini","email":"marco.piraccini@gmail.com"},{"name":"ivan-tymoshenko","email":"ivan@tymoshenko.me"},{"name":"matteo.collina","email":"hello@matteocollina.com"}],"homepage":"https://github.com/platformatic/openapi-schema-validator#readme","bugs":{"url":"https://github.com/platformatic/openapi-schema-validator/issues"},"dist":{"shasum":"414af34112c2a7714a1d8067eda7d0740d349cd8","tarball":"https://registry.npmjs.org/@platformatic/openapi-schema-validator/-/openapi-schema-validator-3.0.0.tgz","fileCount":50,"integrity":"sha512-SHEY5v1Q5EliMaIpXdPCye0QkhFVOoHkEqA8v9qkrO1PqvVOcpii1WqEHYrZZB430sEmrHqEWZInt15EUsR7mw==","signatures":[{"sig":"MEUCIQCSGxMCbyB6byPsOSVzcStsgIqgtP3UCIus7rTIHx/GgwIgYykiKKI+ZF9ABUHbyt3dX/spzMcurrwcz1cob+UJYQw=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":335929},"main":"index.js","type":"module","types":"./index.d.ts","gitHead":"d21c1243d3627bf9a85add3b994ef65e566632bb","scripts":{"lint":"eslint","test":"borp","covtest":"c8 --reporter=lcov npm test","cloneOas":"rm -rf OpenAPI-Specification && git clone --branch 'gh-pages' --single-branch https://github.com/OAI/OpenAPI-Specification.git","posttest":"c8 check-coverage --lines 100 --functions 100 --branches 100","convert31":"node test/convert-3.1.js ","preversion":"npm test","postversion":"git push && git push --tags","preconvert31":"npm run cloneOas","postconvert31":"npm run checkOasVersionsSnapshot","realWorldTest":"node test/realworld/realworld.js","realWorldTestCI":"node test/realworld/realworld.js --ci","checkOasVersions":"node test/check-versions.js","realWorldTestAll":"node test/realworld/realworld.js --all","realWorldTestFailed":"node test/realworld/realworld.js --failedOnly","checkOasVersionsSnapshot":"node test/check-versions.js --updateSnapshot"},"_npmUser":{"name":"matteo.collina","email":"hello@matteocollina.com"},"repository":{"url":"git+https://github.com/platformatic/openapi-schema-validator.git","type":"git"},"_npmVersion":"10.8.2","description":"Validate OpenApi specifications against their JSON schema","directories":{"test":"test"},"_nodeVersion":"20.18.0","dependencies":{"ajv":"^8.17.1","js-yaml":"^4.1.0","ajv-formats":"^3.0.1","ajv-draft-04":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.2","borp":"^0.18.0","eslint":"^9.14.0","neostandard":"^0.11.8"},"_npmOperationalInternal":{"tmp":"tmp/openapi-schema-validator_3.0.0_1731520895423_0.436784801415838","host":"s3://npm-registry-packages"}}},"time":{"created":"2024-11-13T18:01:35.422Z","modified":"2026-04-16T09:48:54.097Z","3.0.0":"2024-11-13T18:01:35.664Z"},"bugs":{"url":"https://github.com/platformatic/openapi-schema-validator/issues"},"author":{"url":"https://platformatic.dev","name":"Platformatic Inc.","email":"oss@platformatic.dev"},"license":"MIT","homepage":"https://github.com/platformatic/openapi-schema-validator#readme","keywords":["openapi","json","schema","validation"],"repository":{"url":"git+https://github.com/platformatic/openapi-schema-validator.git","type":"git"},"description":"Validate OpenApi specifications against their JSON schema","maintainers":[{"email":"mzugm@1368435.ca","name":"mzugm"},{"email":"ivan@tymoshenko.me","name":"ivan-tymoshenko"},{"email":"marco.piraccini@gmail.com","name":"marcopiraccini"},{"email":"leonardo.rossi@gmail.com","name":"leorossi"},{"email":"paolo@cowtech.it","name":"shogun_panda"},{"email":"hello@matteocollina.com","name":"matteo.collina"},{"email":"admin@stephenbelanger.com","name":"qard"},{"email":"luca.maraschi@gmail.com","name":"lucamaraschi"}],"readme":"# OpenAPI schema validator\n\nA JSON schema validator for [OpenAPI](https://www.openapis.org/) specifications,\nit currently supports:\n\n- [2.0](https://spec.openapis.org/oas/v2.0)\n- [3.0.x](https://spec.openapis.org/oas/v3.0.3)\n- [3.1.x](https://spec.openapis.org/oas/v3.1.0)\n\n<a name=\"install\"></a>\n\n## Install\n\n```bash\nnpm install @platformatic/openapi-schema-validator\n```\n\n<a name=\"Usage\"></a>\n\n## Usage\n\nThis module is ESM only, if you need to use commonJS please see below.\n\n```javascript\n// ESM\nimport { Validator } from \"@platformatic/openapi-schema-validator\";\n\nconsole.log(Validator.supportedVersions.has(\"3.1\"));\n// prints true\n\nconst validator = new Validator();\nconst res = await validator.validate(\"./petstore.json\");\nconst specification = validator.specification;\n// specification now contains a Javascript object containing the specification\nif (res.valid) {\n  console.log(\"Specification matches schema for version\", validator.version);\n  const schema = validator.resolveRefs();\n  // schema now contains a Javascript object containing the dereferenced schema\n} else {\n  console.log(\"Specification does not match Schema\");\n  console.log(res.errors);\n}\n```\n\nThis module can be used in CommonJS code via:\n\n```javascript\n// CommonJS\nconst { Validator } = await (import(\"@platformatic/openapi-schema-validator\"));\n```\n\n<a name=\"API\"></a>\n\n## API\n\n- [`new Validator(ajvOptions)`](#newValidator)\n- [`<instance>.validate(specification)`](#validate)\n- [`<instance>.specification`](#specification)\n- [`<instance>.version`](#version)\n- [`<instance>.resolveRefs(options)`](#resolveRefs)\n- [`<instance>.addSpecRef(subSpecification, uri)`](#addSpecRef)\n- [`<instance>.validateBundle([specification,subspecification, ...])`](#validateBundle)\n- [`Validator.supportedVersions`](#supportedVersions)\n\n<a name=\"newValidator\"></a>\n\n### `new Validator(ajvOptions)`\n\nThe constructor returns an instance of `Validator`. By passing an ajv options\nobject it is possible to influence the behavior of the\n[AJV schema validator](https://ajv.js.org/). AJV fails to process the openApi\nschemas if you set `strict:true` therefore this set to `false` if present. This\nis not a bug but a result of the complexity of the openApi JSON schemas.\n\n<a name=\"validate\"></a>\n\n### `<instance>.validate(specification)`\n\nThis function tries to validata a specification against the OpenApi schemas.\n`specification` can be one of:\n\n- a JSON object\n- a JSON object encoded as string\n- a YAML string\n- a filename\n\nExternal references are _not_ automatically resolved so you need to inline them\nyourself if required e.g by using `<instance>.addSpecRef()` The result is an\nobject:\n\n```\n{\n  valid: <boolean>,\n  errors: <any>  // only present if valid is false\n}\n```\n\n<a name=\"specification\"></a>\n\n### `<instance>.specification`\n\nIf the validator managed to extract data from the specification parameter then\nthe extracted specification is available in this property as javascript object.\nE.g. if you supplied a filename of a YAML file and the file was sucessfully read\nand its YAML decoded then the contents is here. Even if validation failed.\n\n<a name=\"version\"></a>\n\n### `<instance>.version`\n\nIf validation is succesfull this will return the openApi version found e.g.\n(\"2.0\",\"3.0\",\"3.1). The openApi specification only specifies major/minor\nversions as separate schemas. So \"3.0.3\" results in \"3.0\".\n\n<a name=\"resolveRefs\"></a>\n\n### `<instance>.resolveRefs(options)`\n\nThis function tries to resolve all internal references. External references are\n_not_ automatically resolved so you need to inline them yourself if required e.g\nby using `<instance>.addSpecRef()`. By default it will use the last\nspecification passed to `<instance>.validate()` but you can explicity pass a\nspecification by passing `{specification:<object>}` as options. The result is an\n`object` where all references have been resolved. Resolution of references is\n`shallow` This should normally not be a problem for this use case.\n\n<a name=\"addSpecRef\"></a>\n\n### `<instance>.addSpecRef(subSpecification, uri)`\n\n`subSpecification` can be one of:\n\n- a JSON object\n- a JSON object encoded as string\n- a YAML string\n- a filename \n\n`uri` must be a string (e.g. `http://www.example.com/subspec`), but\n  is not required if the subSpecification holds a `$id` attribute at top level.\n  If you specify a value for `uri` it will overwrite the definition in the `$id`\n  attribute at top level.\n\nSometimes a specification is composed of multiple files that each contain parts\nof the specification. The specification refers to these sub specifications using\n`external references`. Since references are based on URI's (so `Identifier` and not\n`Location` as in URL's!) there needs to be a way to tell the validator how to\nresolve those references. This is where this function comes in:\n\nE.g.: we have a main specification in `main-spec.yaml` containing:\n\n```yaml\n...\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: ''\n      operationId: addPet\n      responses:\n        '405':\n          description: Invalid input\n      requestBody:\n        $ref: 'http://www.example.com/subspec#/components/requestBodies/Pet'\n```\n\nAnd the reference is in `sub-spec.yaml`, containing:\n\n```yaml\ncomponents:\n  requestBodies:\n    Pet:\n      content:\n        application/json:\n          schema:\n            $ref: '#/components/schemas/Pet'\n        application/xml:\n          schema:\n            $ref: '#/components/schemas/Pet'\n      description: Pet object that needs to be added to the store\n      required: true\n  ...\n```\n\nThen the validation can be performed as follows:\n\n```javascript\nimport { Validator } from \"@platformatic/openapi-schema-validator\";\nconst validator = new Validator();\nawait validator.addSpecRef(\"./sub-spec.yaml\", \"http://www.example.com/subspec\");\nconst res = await validator.validate(\"./main-spec.yaml\");\n// res now contains the results of the validation across main-spec and sub-spec\nconst specification = validator.specification;\n// specification now contains a Javascript object containing the specification\n// with the subspec inlined\n```\n\n<a name=\"validateBundle\"></a>\n\n### `<instance>.validateBundle([specification,subspecification, ...])`\n\nThis offers an alternative to the combination of `addSpecRef` and `validate`.\nYou can pass an array of (sub)specifications where each can be one of:\n\n- a JSON object\n- a JSON object encoded as string\n- a YAML string\n- a filename\n\nThere can only be one main specification present (starting with swagger/openapi) but it does not have to be the first one. If you provide filenames and the files do not have `$id` attributes, then the `$id` attribute will be generated from the filename.\n\nIf we take the YAML specifications from the previous example then validation can be performed as follows:\n\n```javascript\nimport { Validator } from \"@platformatic/openapi-schema-validator\";\nconst validator = new Validator();\nconst res = await validator.validateBundle([ \"./sub-spec.yaml\", \"./main-spec.yaml\"]);\n// res now contains the results of the validation across main-spec and sub-spec\nconst specification = validator.specification;\n// specification now contains a Javascript object containing the specification\n// with the subspec inlined\n```\n\n<a name=\"supportedVersions\"></a>\n\n### `Validator.supportedVersions`\n\nThis static property returns the OpenApi versions supported by this package as a\n`Set`. If present, the result of `<instance>.version` is a member of this `Set`.\n\n<a name=\"license\"></a>\n\n# Credits\n\nThis module was forked from\n[https://github.com/seriousme/openapi-schema-validator](https://github.com/seriousme/openapi-schema-validator)\nat [commit](https://github.com/seriousme/openapi-schema-validator/commit/e4f417ade9e675225381fb872e1b78a9fa392472).\nWe thank Hans Klunder for his original work on this module.\n\n# License\n\nLicensed under the [MIT license](LICENSE.txt)\n","readmeFilename":"README.md"}