OpenAPI Schema to JSON Schema
A little NodeJS package to convert OpenAPI Schema Object or Parameter Object to JSON Schema.
OpenAPI is a specification for describing RESTful APIs. OpenAPI v3.0 allows us to describe the structures of request and response payloads in a detailed manner. This would, theoretically, mean that we should be able to automatically validate request and response payloads. However, as of writing there aren't many validators around.
The good news is that there are many validators for JSON Schema for different languages. The bad news is that OpenAPI v3.0 is not entirely compatible with JSON Schema. The Schema Object of OpenAPI v3.0 is an extended subset of JSON Schema Specification Wright Draft 00 with some differences. This will be resolved in OpenAPI v3.1, but until then... this tool will fill that gap.
There is also a CLI tool for creating a JSON of schemas from the whole API specification.
If you need to do the conversion in reverse, checkout json-schema-to-openapi-schema.
- converts OpenAPI v3.0 Schema Object to JSON Schema Draft 4
- converts OpenAPI v3.0 Parameter Object to JSON Schema Draft 4
- supports deep structures with nested
- removes OpenAPI specific properties such as
deprecatedetc. unless specified otherwise
- optionally supports
x-patternPropertiesin the Schema Object
$refs are not handled in any way, so please use a resolver such as json-ref-resolver prior to using this package.
npm install --save @openapi-contrib/openapi-schema-to-json-schema
Converting OpenAPI schema
Here's a small example to get the idea:
var toJsonSchema = ;var schema =type: 'string'format: 'date-time'nullable: true;var convertedSchema = ;console;
The example prints out
type: 'string' 'null'format: 'date-time''$schema': '#'
Provide the function the schema object with possible options.
The function accepts
options object as the second argument.
If set to
false, converts the provided schema in place. If
true, clones the schema by converting it to JSON and back. The overhead of the cloning is usually negligible. Defaults to
false by default and leaves
date format as is. If set to
format: 'date' to
var schema =type: 'string'format: 'date';var convertedSchema = ;console;
type: 'string'format: 'date-time''$schema': '#'
By default, the following fields are removed from the result schema:
deprecated as they are not supported by JSON Schema Draft 4. Provide an array of the ones you want to keep (as strings) and they won't be removed.
If set to
true, will remove properties set as
readOnly. If the property is set as
required, it will be removed from the
required array as well. The property will be removed even if
readOnly is set to be kept with
removeReadOnly, but for
If set to
x-patternProperties property is present, change
patternProperties and call
patternPropertiesHandler is not defined, call the default handler. See
patternPropertiesHandler for more information.
Provide a function to handle pattern properties and set
supportPatternProperties to take effect. The function takes the schema where
x-patternProperties is defined on the root level. At this point
x-patternProperties is changed to
patternProperties. It must return the modified schema.
If the handler is not provided, the default handler is used. If
additionalProperties is set and is an object, the default handler sets it to false if the
additionalProperties object has deep equality with a pattern object inside
patternProperties. This is because we might want to define
additionalProperties in OpenAPI spec file, but want to validate against a pattern. The pattern would turn out to be useless if
additionalProperties of the same structure were allowed. Create you own handler to override this functionality.
test/pattern_properties.test.js for examples how this works.
Converting OpenAPI parameters
OpenAPI parameters can be converted:
var toJsonSchema = fromParameter;var param =name: 'parameter name'in: 'query'schema:type: 'string'format: 'date'var convertedSchema = ;console;
The result is as follows:
type: 'string'format: 'date''$schema': '#'
When a parameter has several schemas (one per MIME type) a map is returned instead.
would be converted to:
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.