Converts a JSON Schema to OpenAPI Schema Object
npm install @openapi-contrib/json-schema-to-openapi-schemaA little NodeJS package to convert JSON Schema to a OpenAPI Schema Object.
- converts JSON Schema Draft 04 to OpenAPI 3.0 Schema Object
- switches type: ['foo', 'null'] to type: foo and nullable: true
- supports deep structures with nested allOfs etc.
- switches patternProperties to x-patternProperties
- converts dependencies to an allOf + oneOf OpenAPI-valid equivalent
``shell`
npm install --save @openapi-contrib/json-schema-to-openapi-schema
Requires NodeJS v10 or greater.
Here's a small example to get the idea:
`ts
import { convert } from '@openapi-contrib/json-schema-to-openapi-schema';
const schema = {
$schema: 'http://json-schema.org/draft-04/schema#',
type: ['string', 'null'],
format: 'date-time',
};
(async () => {
const convertedSchema = await convert(schema);
console.log(convertedSchema);
})();
`
The example prints out
`js`
{
type: 'string',
format: 'date-time',
nullable: true
}
The function accepts options object as the second argument.
#### cloneSchema (boolean)
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 true.
#### dereference (boolean)
If set to true, all local and remote references (http/https and file) $refs will be dereferenced. Defaults to false.
#### convertUnreferencedDefinitions (boolean)
Defaults to true.
If a schema had a definitions property (which is valid in JSONSchema), and only some of those entries are referenced, we'll still try and convert the remaining definitions to OpenAPI. If you do not want this behavior, set this to false.
#### dereferenceOptions (object = $RefParser.Options)
Options to pass to the dereferencer (@apidevtools/json-schema-ref-parser). To prevent circular references, pass { dereference: { circular: 'ignore' } }.
`sh
Usage:
json-schema-to-openapi-schema
Commands:
convert Converts JSON Schema Draft 04 to OpenAPI 3.0 Schema Object
Options:
-h, --help Show help for any command
-v, --version Output the CLI version number
-d, --dereference If set all local and remote references (http/https and file) $refs will be dereferenced
`
For synchronous conversion without async operations, use convertSync:
`ts
import { convertSync } from '@openapi-contrib/json-schema-to-openapi-schema';
const schema = {
$schema: 'http://json-schema.org/draft-04/schema#',
type: ['string', 'null'],
format: 'date-time',
};
const convertedSchema = convertSync(schema);
console.log(convertedSchema);
`
This will output the same result as the async version:
`js`
{
type: 'string',
format: 'date-time',
nullable: true
}
convertSync supports a subset of the options available to convert:
#### cloneSchema (boolean)
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 true.
#### convertUnreferencedDefinitions (boolean)
Defaults to true.
If a schema has a definitions property (valid in JSON Schema), and only some entries are referenced, we'll still try to convert the remaining definitions to OpenAPI. If you do not want this behavior, set this to false.
convertSync does not support dereferencing external references ($ref to HTTP/HTTPS URLs or external files). If your schema contains external references, use the async convert function with the dereference: true option instead.
#### Example:
`ts
// Schema with external reference
const schema = {
type: 'object',
properties: {
user: {
$ref: 'https://example.com/schemas/user.json',
},
},
};
// convertSync leaves the reference unresolved
const result = convertSync(schema);
// Result: { type: 'object', properties: { user: { $ref: 'https://example.com/schemas/user.json' } } }
// Use async convert for proper resolution:
const resolved = await convert(schema, { dereference: true });
`
Note: External references will remain as $ref pointers in the output schema. They will not be expanded or validated.
OpenAPI is often described as an extension of JSON Schema, but both specs have changed over time and grown independently. OpenAPI v2 was based on JSON Schema draft v4 with a long list of deviations, but OpenAPI v3 shrank that list, upping their support to draft v4 and making the list of discrepancies shorter. This has been solved for OpenAPI v3.1, but for those using OpenAPI v3.0, you can use this tool to solve the divergence.
This tool sets out to allow folks to convert from JSON Schema (their one source of truth for everything) to OpenAPI (a thing for HTML docs and making SDKs).
- From: JSON Schema Draft v5 †
- To: OpenAPI 3.0
_† Draft v5 is also known as Draft Wright 00, as the drafts are often named after the author, and this was the first one by A. Wright. Amongst other things, draft v5 aimed to rewrite the meta files, but the experiment failed, meaning we need to continue to use the draft v4 metafiles. Ugh._
To convert the other way, check out [openapi-schema-to-json-schema], which this package was based on.
To run the test-suite:
`shell``
npm test
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.
- [Stoplight][] for donating time and effort to this project, and many more.
- [mikunn][] for creating [openapi-schema-to-json-schema] which this is based on.
- [Phil Sturgeon][] for flipping that conversion script about face.
- [WeWork][] for giving this a home for a while.
- [All Contributors][link-contributors]
[mikunn]: https://github.com/mikunn
[wework]: https://github.com/wework
[stoplight]: https://stoplight.io/
[phil sturgeon]: https://github.com/philsturgeon
[openapi-schema-to-json-schema]: https://github.com/openapi-contrib/openapi-schema-to-json-schema
[link-contributors]: https://github.com/openapi-contrib/json-schema-to-openapi-schema/graphs/contributors