https://github.com/jaredce/json-schema-to-openapi-schema-object
Converts a standard JSON Schema to a compatible Open API v3 Schema Object
https://github.com/jaredce/json-schema-to-openapi-schema-object
Last synced: 8 months ago
JSON representation
Converts a standard JSON Schema to a compatible Open API v3 Schema Object
- Host: GitHub
- URL: https://github.com/jaredce/json-schema-to-openapi-schema-object
- Owner: JaredCE
- License: apache-2.0
- Created: 2022-05-21T11:27:17.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-09T13:19:42.000Z (almost 2 years ago)
- Last Synced: 2025-02-02T04:41:48.388Z (over 1 year ago)
- Language: JavaScript
- Size: 229 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# json-schema-for-openapi
Converts a standard [JSON Schema](https://json-schema.org/understanding-json-schema/index.html) to a compatible [OpenAPI v3.0.X Schema Object](https://spec.openapis.org/oas/v3.0.3#schema-object).
As of version 0.3.0, it is now advised to run a schema through a de-referencer like: https://apitools.dev/json-schema-ref-parser/ to properly deal with `$ref`. I have removed my own poor implementation of de-referencing JSON schemas since there are libraries that can do it better than I can.
It should be noted, that de-referencing libraries have their own issues and might not be able to properly parse your JSON/output a schema you might expect. Due to the way OpenAPI v3.0.X Schema Object's are handled, should the referencing not be 100% correct you might face issues using this library and its output to be used with OpenAPI 3.0.X.
## Conversions
This attempts to massage the standard JSON Schema to a compatible OpenAPI v3.0.X Schema Object. There are many properties that are not supported by OpenAPI v3.0.X Schema Object, though have now been supported by [OpenAPI v3.1.X](https://spec.openapis.org/oas/v3.1.0#schema-object). This library should only be used if working with OpenAPI v3.0.X.
### Items as an Array to Object
This will convert a schema of:
```json
{
"type": "object",
"properties": {
"example": {
"type": "array",
"items": [
{
"type": "string"
}
]
}
}
}
```
To:
```json
{
"type": "object",
"properties": {
"example": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
```
At the moment, this library cannot handle more than one item in the array, and so will default to using the first item only.
### Types in an array to OneOf
This will convert a schema of:
```json
{
"type": "object",
"properties": {
"example": {
"type": ["string", "number"]
}
}
}
```
To:
```json
{
"type": "object",
"properties": {
"example": {
"oneOf": [
{
"type": "string"
},
{
"type": "number"
}
]
}
}
}
```
Where an array contains `null`, it will now set `nullable` against all types:
```json
{
"type": "object",
"properties": {
"example": {
"type": ["string", "number", "null"]
}
}
}
```
To:
```json
{
"type": "object",
"properties": {
"example": {
"oneOf": [
{
"type": "string",
"nullable": true
},
{
"type": "number",
"nullable": true
}
]
}
}
}
```
### Const to enum
This will convert a schema of:
```json
{
"type": "object",
"properties": {
"example": {
"type": "string",
"const": "Surburbia"
}
}
}
```
To:
```json
{
"type": "object",
"properties": {
"example": {
"type": "string",
"enum": ["Surburbia"]
}
}
}
```
### null types
OpenAPI 3.0.X does not allow for null as a type, so will convert a schema of:
```json
{
"type": "object",
"properties": {
"example": {
"type": "null"
}
}
}
```
To:
```json
{
"type": "object",
"properties": {
"example": {
"nullable": true
}
}
}
```
### Default to their type
This will convert the `"default":` value to the relevant type. A String to a String, a Number/Integer to a number/Integer, a Boolean to a Boolean and try to manipulate an Object or an Array to either an Object or an Array
### Dependencies, DependentRequired, DependentSchemas
This will try to convert `"dependencies":`, `"dependentRequired":` and `"dependentSchemas":` to a valid `"allOf"` in the case of a `"dependentSchemas"` or an `"anyOf":` schema in the case of a `"dependentRequired"`.
### If/Then/Else
It will try to convert an If/Then/Else schema statement to a valid `"OneOf"` schema.
## Installation and Usage:
Install via npm: `npm install json-schema-for-openapi`.
And use as a Factory like:
```js
const ConvertorFactory = require("json-schema-for-openapi");
const jsonSchema = {
$schema: "http://json-schema.org/draft-04/schema#",
title: "JSON API Schema",
description:
"This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
type: "object",
properties: {
errors: {
type: "object",
},
},
};
const convertedSchema = ConvertorFactory.convert(jsonSchema, "main");
```
which will output:
```json
{
"schemas": {
"main": {
"title": "JSON API Schema",
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
"type": "object",
"properties": {
"errors": {
"type": "object"
}
}
}
}
}
```