Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@openapi-contrib/json-schema-to-openapi-schema

Package Overview
Dependencies
Maintainers
1
Versions
20
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@openapi-contrib/json-schema-to-openapi-schema

Converts a JSON Schema to OpenAPI Schema Object

  • 3.0.2
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
19K
decreased by-1.14%
Maintainers
1
Weekly downloads
 
Created
Source

JSON Schema to OpenAPI Schema

A little NodeJS package to convert JSON Schema to a OpenAPI Schema Object.

Treeware

Features

  • 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

Installation

npm install --save @openapi-contrib/json-schema-to-openapi-schema

Requires NodeJS v10 or greater.

Usage

Here's a small example to get the idea:

const convert = require('@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

{
  type: 'string',
  format: 'date-time',
  nullable: true
}

Options

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' } }.

Command Line

Usage:
    json-schema-to-openapi-schema <command> [options] <file>

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

Why?

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.

Diagram showing data model (the objects, payload bodies, etc) and service model (endpoints, headers, metadata, etc)

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).

Versions

† 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.

Converting Back

To convert the other way, check out openapi-schema-to-json-schema, which this package was based on.

Tests

To run the test-suite:

npm test

Treeware

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.

Thanks

FAQs

Package last updated on 02 Jun 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc