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
92.9
Supply Chain
100
Quality
88.8
Maintenance
100
Vulnerability
99.6
License
Updated on 28 Nov 2024
JavaScript (100%)
Cumulative downloads
Total Downloads
Last day
-6.4%
Compared to previous day
Last week
-3.4%
Compared to previous week
Last month
6.1%
Compared to previous month
Last year
743.3%
Compared to previous year
5
2
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 validata 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 sucessfully read and its YAML decoded then the contents is here. Even if validation failed.
<instance>.version
If validation is succesfull 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 explicity 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
.
Licensed under the MIT license
No vulnerabilities found.
Reason
30 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 10
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
packaging workflow detected
Details
Reason
SAST tool is run on all commits
Details
Reason
1 existing vulnerabilities detected
Details
Reason
dependency not pinned by hash detected -- score normalized to 4
Details
Reason
Found 1/18 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
Reason
project is not fuzzed
Details
Reason
branch protection not enabled on development/release branches
Details
Score
Last Scanned on 2024-11-25
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More