Gathering detailed insights and metrics for @seriousme/openapi-schema-validator
Gathering detailed insights and metrics for @seriousme/openapi-schema-validator
Gathering detailed insights and metrics for @seriousme/openapi-schema-validator
Gathering detailed insights and metrics for @seriousme/openapi-schema-validator
OpenApi schema validation for OpenApi versions v2, v3.0.x and v3.1.x
npm install @seriousme/openapi-schema-validator
Typescript
Module System
Node Version
NPM Version
JavaScript (96.02%)
TypeScript (3.98%)
Total Downloads
9,555,670
Last Day
1,657
Last Week
38,875
Last Month
139,775
Last Year
3,765,499
MIT License
56 Stars
663 Commits
11 Forks
2 Watchers
2 Branches
5 Contributors
Updated on Aug 25, 2025
Latest Version
2.5.0
Package Id
@seriousme/openapi-schema-validator@2.5.0
Unpacked Size
348.16 kB
Size
50.85 kB
File Count
63
NPM Version
11.5.2
Node Version
22.18.0
Published on
Aug 19, 2025
Cumulative downloads
Total Downloads
Last Day
40.2%
1,657
Compared to previous day
Last Week
15.3%
38,875
Compared to previous week
Last Month
-24.6%
139,775
Compared to previous month
Last Year
-29.6%
3,765,499
Compared to previous year
4
6
A JSON schema validator for OpenAPI specifications, it currently supports:
Tested on over 2,000 real-world APIs from AWS, Microsoft, Google etc.
1npm install @seriousme/openapi-schema-validator
This module is ESM only, if you need to use commonJS please see below.
1// ESM 2import { Validator } from "@seriousme/openapi-schema-validator"; 3 4console.log(Validator.supportedVersions.has("3.1")); 5// prints true 6 7const validator = new Validator(); 8const res = await validator.validate("./petstore.json"); 9const specification = validator.specification; 10// specification now contains a Javascript object containing the specification 11if (res.valid) { 12 console.log("Specification matches schema for version", validator.version); 13 const schema = validator.resolveRefs(); 14 // schema now contains a Javascript object containing the dereferenced schema 15} else { 16 console.log("Specification does not match Schema"); 17 console.log(res.errors); 18}
This module can be used in CommonJS code via:
1// CommonJS 2const { Validator } = await (import("@seriousme/openapi-schema-validator"));
See also the upgrading guide if you come from a previous major version.
Run with global install:
1npm install @seriousme/openapi-schema-validator -g 2validate-api <filename>
Run without install:
1npx -p @seriousme/openapi-schema-validator validate-api <filename>
Where <filename>
refers to a YAML or JSON file containing the specification.
To make it easier to combine multiple YAML or JSON files into a single specification file there is the bundle-api
command.
(see the validateBundle section below)
1npm install @seriousme/openapi-schema-validator -g 2bundle-api <specFiles>
Run without install:
1npx -p @seriousme/openapi-schema-validator bundle-api <spec files>
The output will be a validated JSON specification.
Options:
-o --output
new Validator(ajvOptions)
<instance>.validate(specification)
<instance>.specification
<instance>.version
<instance>.resolveRefs(options)
<instance>.addSpecRef(subSpecification, uri)
<instance>.validateBundle([specification,subspecification, ...])
Validator.supportedVersions
new Validator(ajvOptions)
The constructor returns an instance of Validator
. By passing an ajv options
object it is possible to influence the behavior of the
AJV schema validator. AJV fails to process the openApi
schemas if you set strict:true
therefore this set to false
if present. This
is not a bug but a result of the complexity of the openApi JSON schemas.
<instance>.validate(specification)
This function tries to validate a specification against the OpenApi schemas.
specification
can be one of:
External references are not automatically resolved so you need to inline them
yourself if required e.g by using <instance>.addSpecRef()
The result is an
object:
{
valid: <boolean>,
errors: <any> // only present if valid is false
}
<instance>.specification
If the validator managed to extract data from the specification parameter then the extracted specification is available in this property as javascript object. E.g. if you supplied a filename of a YAML file and the file was successfully read and its YAML decoded then the contents is here. Even if validation failed.
<instance>.version
If validation is successful this will return the openApi version found e.g. ("2.0","3.0","3.1). The openApi specification only specifies major/minor versions as separate schemas. So "3.0.3" results in "3.0".
<instance>.resolveRefs(options)
This function tries to resolve all internal references. External references are
not automatically resolved so you need to inline them yourself if required e.g
by using <instance>.addSpecRef()
. By default it will use the last
specification passed to <instance>.validate()
but you can explicitly pass a
specification by passing {specification:<object>}
as options. The result is an
object
where all references have been resolved. Resolution of references is
shallow
This should normally not be a problem for this use case.
<instance>.addSpecRef(subSpecification, uri)
subSpecification
can be one of:
uri
must be a string (e.g. http://www.example.com/subspec
), but
is not required if the subSpecification holds a $id
attribute at top level.
If you specify a value for uri
it will overwrite the definition in the $id
attribute at top level.
Sometimes a specification is composed of multiple files that each contain parts
of the specification. The specification refers to these sub specifications using
external references
. Since references are based on URI's (so Identifier
and not
Location
as in URL's!) there needs to be a way to tell the validator how to
resolve those references. This is where this function comes in:
E.g.: we have a main specification in main-spec.yaml
containing:
1... 2paths: 3 /pet: 4 post: 5 tags: 6 - pet 7 summary: Add a new pet to the store 8 description: '' 9 operationId: addPet 10 responses: 11 '405': 12 description: Invalid input 13 requestBody: 14 $ref: 'http://www.example.com/subspec#/components/requestBodies/Pet'
And the reference is in sub-spec.yaml
, containing:
1components: 2 requestBodies: 3 Pet: 4 content: 5 application/json: 6 schema: 7 $ref: '#/components/schemas/Pet' 8 application/xml: 9 schema: 10 $ref: '#/components/schemas/Pet' 11 description: Pet object that needs to be added to the store 12 required: true 13 ...
Then the validation can be performed as follows:
1import { Validator } from "@seriousme/openapi-schema-validator"; 2const validator = new Validator(); 3await validator.addSpecRef("./sub-spec.yaml", "http://www.example.com/subspec"); 4const res = await validator.validate("./main-spec.yaml"); 5// res now contains the results of the validation across main-spec and sub-spec 6const specification = validator.specification; 7// specification now contains a Javascript object containing the specification 8// with the subspec inlined
<instance>.validateBundle([specification,subspecification, ...])
This offers an alternative to the combination of addSpecRef
and validate
.
You can pass an array of (sub)specifications where each can be one of:
There 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.
If we take the YAML specifications from the previous example then validation can be performed as follows:
1import { Validator } from "@seriousme/openapi-schema-validator"; 2const validator = new Validator(); 3const res = await validator.validateBundle([ "./sub-spec.yaml", "./main-spec.yaml"]); 4// res now contains the results of the validation across main-spec and sub-spec 5const specification = validator.specification; 6// specification now contains a Javascript object containing the specification 7// with the subspec inlined
Validator.supportedVersions
This static property returns the OpenApi versions supported by this package as a
Set
. If present, the result of <instance>.version
is a member of this Set
.
The JSONschemas are copied from the OpenAPI specification JSONschemas which might differ from the OpenAPI specification HTML pages! If you find a bug in a schema (e.g. because it behaves differently than specified in the HTML) then please raise an issue at https://github.com/OAI/OpenAPI-Specification. Shortly after the specification writers update their schema the automation will pick it up and include the updated version in this module.
Licensed under the MIT license
No vulnerabilities found.