{"id":13903068,"url":"https://github.com/seriousme/openapi-schema-validator","last_synced_at":"2025-04-04T15:09:29.739Z","repository":{"id":36976658,"uuid":"365588968","full_name":"seriousme/openapi-schema-validator","owner":"seriousme","description":"OpenApi schema validation for OpenApi versions v2, v3.0.x and v3.1.x","archived":false,"fork":false,"pushed_at":"2025-03-21T05:58:39.000Z","size":919,"stargazers_count":47,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T14:09:19.588Z","etag":null,"topics":["cli","javascript","jsonschema","openapi","openapi-schema-validator","openapi3","openapi3-1","openapi3-validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seriousme.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-08T18:50:37.000Z","updated_at":"2025-03-21T05:58:40.000Z","dependencies_parsed_at":"2024-01-15T19:07:24.089Z","dependency_job_id":"34ffebc9-c8a6-47ce-bdc6-a5a73c708963","html_url":"https://github.com/seriousme/openapi-schema-validator","commit_stats":{"total_commits":386,"total_committers":5,"mean_commits":77.2,"dds":0.3523316062176166,"last_synced_commit":"930cc7a58aad8917ae117c900ed97bca6381cdec"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Fopenapi-schema-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Fopenapi-schema-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Fopenapi-schema-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Fopenapi-schema-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seriousme","download_url":"https://codeload.github.com/seriousme/openapi-schema-validator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198461,"owners_count":20900080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","javascript","jsonschema","openapi","openapi-schema-validator","openapi3","openapi3-1","openapi3-validation"],"created_at":"2024-08-06T22:01:35.846Z","updated_at":"2025-04-04T15:09:29.711Z","avatar_url":"https://github.com/seriousme.png","language":"JavaScript","readme":"# OpenAPI schema validator\n\n[![CI status](https://github.com/seriousme/openapi-schema-validator/workflows/Node.js%20CI/badge.svg)](https://github.com/seriousme/openapi-schema-validator/actions?query=workflow%3A%22Node.js+CI%22)\n[![Coverage Status](https://coveralls.io/repos/github/seriousme/openapi-schema-validator/badge.svg?branch=master)](https://coveralls.io/github/seriousme/openapi-schema-validator?branch=master)\n[![NPM version](https://img.shields.io/npm/v/@seriousme/openapi-schema-validator.svg)](https://www.npmjs.com/package/@seriousme/openapi-schema-validator)\n![npm](https://img.shields.io/npm/dm/@seriousme/openapi-schema-validator)\n[![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://apis.guru/browse-apis/)\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\nTested on [over 2,000 real-world APIs](https://apis.guru/browse-apis/) from AWS,\nMicrosoft, Google etc.\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n\n## Install\n\n```bash\nnpm install @seriousme/openapi-schema-validator\n```\n\n\u003ca name=\"Usage\"\u003e\u003c/a\u003e\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 \"@seriousme/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(\"@seriousme/openapi-schema-validator\"));\n```\n\nSee also the [upgrading guide](UPGRADING.md) if you come from a previous major version.\n\n\u003ca name=\"CLI\"\u003e\u003c/a\u003e\n\n### CLI for API validation\n\nRun with global install:\n\n```bash\nnpm install @seriousme/openapi-schema-validator -g\nvalidate-api \u003cfilename\u003e\n```\n\nRun without install:\n\n```bash\nnpx -p @seriousme/openapi-schema-validator validate-api \u003cfilename\u003e\n```\n\nWhere `\u003cfilename\u003e` refers to a YAML or JSON file containing the specification.\n\n### CLI for API bundling\n\nTo make it easier to combine multiple YAML or JSON files into a single specification file there is the `bundle-api` command.\n(see the [validateBundle](#validateBundle) section below) \n\n```bash\nnpm install @seriousme/openapi-schema-validator -g\nbundle-api \u003cspecFiles\u003e \n```\n\nRun without install:\n\n```bash\nnpx -p @seriousme/openapi-schema-validator bundle-api \u003cspec files\u003e \n```\n\nThe output will be a validated JSON specification.\nOptions:\n  -o  --output \u003cfilename\u003e   the filename to save the output to, default is STDOUT.\n  -t  --type  [JSON|YAML]   the output format, default is JSON.\n\n\u003ca name=\"API\"\u003e\u003c/a\u003e\n\n## API\n\n- [`new Validator(ajvOptions)`](#newValidator)\n- [`\u003cinstance\u003e.validate(specification)`](#validate)\n- [`\u003cinstance\u003e.specification`](#specification)\n- [`\u003cinstance\u003e.version`](#version)\n- [`\u003cinstance\u003e.resolveRefs(options)`](#resolveRefs)\n- [`\u003cinstance\u003e.addSpecRef(subSpecification, uri)`](#addSpecRef)\n- [`\u003cinstance\u003e.validateBundle([specification,subspecification, ...])`](#validateBundle)\n- [`Validator.supportedVersions`](#supportedVersions)\n\n\u003ca name=\"newValidator\"\u003e\u003c/a\u003e\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\u003ca name=\"validate\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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 `\u003cinstance\u003e.addSpecRef()` The result is an\nobject:\n\n```\n{\n  valid: \u003cboolean\u003e,\n  errors: \u003cany\u003e  // only present if valid is false\n}\n```\n\n\u003ca name=\"specification\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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\u003ca name=\"version\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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\u003ca name=\"resolveRefs\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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 `\u003cinstance\u003e.addSpecRef()`. By default it will use the last\nspecification passed to `\u003cinstance\u003e.validate()` but you can explicity pass a\nspecification by passing `{specification:\u003cobject\u003e}` 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\u003ca name=\"addSpecRef\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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 \"@seriousme/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\u003ca name=\"validateBundle\"\u003e\u003c/a\u003e\n\n### `\u003cinstance\u003e.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 \"@seriousme/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\u003ca name=\"supportedVersions\"\u003e\u003c/a\u003e\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 `\u003cinstance\u003e.version` is a member of this `Set`.\n\n\u003ca name=\"notes\"\u003e\u003c/a\u003e\n\n# Notes\n\nThe [JSONschemas](/schemas/) are copied from the [OpenAPI specification JSONschemas](https://github.com/OAI/OpenAPI-Specification/tree/gh-pages) which might differ from the [OpenAPI specification HTML pages](https://spec.openapis.org/oas/latest.html)! \nIf you find a bug in a schema (e.g. because it behaves differently than specified in the HTML) then \nplease raise an issue at https://github.com/OAI/OpenAPI-Specification.\nShortly after the specification writers update their schema the automation will pick it up \nand include the updated version in this module.\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n\n# License\n\nLicensed under the [MIT license](LICENSE.txt)\n","funding_links":[],"categories":["cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseriousme%2Fopenapi-schema-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseriousme%2Fopenapi-schema-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseriousme%2Fopenapi-schema-validator/lists"}