Skip to content

Commit 8c1a424

Browse files
JaredCEJaredCE
authored
Merge pull request #28 from JaredCE/improve-circular-reference-handling
Improve circular reference handling
2 parents 519156a + d17e562 commit 8c1a424

File tree

5 files changed

+163
-124
lines changed

5 files changed

+163
-124
lines changed

‎README.md

Lines changed: 109 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,57 @@
1-
![Node.js CI](https://github.com/JaredCE/json-schema-to-openAPI-schema-object/actions/workflows/node.js.yml/badge.svg)
2-
![version](https://img.shields.io/npm/v/json-schema-for-openapi.svg?style=flat-square)
3-
1+
<p>
2+
<a href="https://www.npmjs.com/package/json-schema-for-openapi">
3+
<img src="https://img.shields.io/npm/v/json-schema-for-openapi.svg?style=flat-square">
4+
</a>
5+
<a href="https://github.com/JaredCE/json-schema-to-openAPI-schema-object/actions/workflows/node.js.yml">
6+
<img src="https://github.com/JaredCE/json-schema-to-openAPI-schema-object/actions/workflows/node.js.yml/badge.svg">
7+
</a>
8+
</p>
49

510
# json-schema-for-openapi
611

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

9-
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.
14+
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.
1015

11-
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.
16+
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.
1217

1318
## Conversions
1419

15-
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.
20+
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.
1621

1722
### Items as an Array to Object
1823

1924
This will convert a schema of:
25+
2026
```json
2127
{
22-
"type": "object",
23-
"properties": {
24-
"example": {
25-
"type": "array",
26-
"items": [
27-
{
28-
"type": "string"
29-
}
30-
]
28+
"type": "object",
29+
"properties": {
30+
"example": {
31+
"type": "array",
32+
"items": [
33+
{
34+
"type": "string"
3135
}
36+
]
3237
}
38+
}
3339
}
3440
```
3541

3642
To:
3743

3844
```json
3945
{
40-
"type": "object",
41-
"properties": {
42-
"example": {
43-
"type": "array",
44-
"items": {
45-
"type": "string"
46-
}
47-
}
46+
"type": "object",
47+
"properties": {
48+
"example": {
49+
"type": "array",
50+
"items": {
51+
"type": "string"
52+
}
4853
}
54+
}
4955
}
5056
```
5157

@@ -57,67 +63,67 @@ This will convert a schema of:
5763

5864
```json
5965
{
60-
"type": "object",
61-
"properties": {
62-
"example": {
63-
"type": ["string", "number"],
64-
}
66+
"type": "object",
67+
"properties": {
68+
"example": {
69+
"type": ["string", "number"]
6570
}
71+
}
6672
}
6773
```
6874

6975
To:
7076

7177
```json
7278
{
73-
"type": "object",
74-
"properties": {
75-
"example": {
76-
"oneOf": [
77-
{
78-
"type": "string"
79-
},
80-
{
81-
"type": "number"
82-
}
83-
]
79+
"type": "object",
80+
"properties": {
81+
"example": {
82+
"oneOf": [
83+
{
84+
"type": "string"
85+
},
86+
{
87+
"type": "number"
8488
}
89+
]
8590
}
91+
}
8692
}
8793
```
8894

8995
Where an array contains `null`, it will now set `nullable` against all types:
9096

9197
```json
9298
{
93-
"type": "object",
94-
"properties": {
95-
"example": {
96-
"type": ["string", "number", "null"],
97-
}
99+
"type": "object",
100+
"properties": {
101+
"example": {
102+
"type": ["string", "number", "null"]
98103
}
104+
}
99105
}
100106
```
101107

102108
To:
103109

104110
```json
105111
{
106-
"type": "object",
107-
"properties": {
108-
"example": {
109-
"oneOf": [
110-
{
111-
"type": "string",
112-
"nullable": true
113-
},
114-
{
115-
"type": "number",
116-
"nullable": true
117-
}
118-
]
112+
"type": "object",
113+
"properties": {
114+
"example": {
115+
"oneOf": [
116+
{
117+
"type": "string",
118+
"nullable": true
119+
},
120+
{
121+
"type": "number",
122+
"nullable": true
119123
}
124+
]
120125
}
126+
}
121127
}
122128
```
123129

@@ -127,27 +133,27 @@ This will convert a schema of:
127133

128134
```json
129135
{
130-
"type": "object",
131-
"properties": {
132-
"example": {
133-
"type": "string",
134-
"const": "Surburbia"
135-
}
136+
"type": "object",
137+
"properties": {
138+
"example": {
139+
"type": "string",
140+
"const": "Surburbia"
136141
}
142+
}
137143
}
138144
```
139145

140146
To:
141147

142148
```json
143149
{
144-
"type": "object",
145-
"properties": {
146-
"example": {
147-
"type": "string",
148-
"enum": ["Surburbia"]
149-
}
150+
"type": "object",
151+
"properties": {
152+
"example": {
153+
"type": "string",
154+
"enum": ["Surburbia"]
150155
}
156+
}
151157
}
152158
```
153159

@@ -157,31 +163,31 @@ OpenAPI 3.0.X does not allow for null as a type, so will convert a schema of:
157163

158164
```json
159165
{
160-
"type": "object",
161-
"properties": {
162-
"example": {
163-
"type": "null",
164-
}
166+
"type": "object",
167+
"properties": {
168+
"example": {
169+
"type": "null"
165170
}
171+
}
166172
}
167173
```
168174

169175
To:
170176

171177
```json
172178
{
173-
"type": "object",
174-
"properties": {
175-
"example": {
176-
"nullable": true,
177-
}
179+
"type": "object",
180+
"properties": {
181+
"example": {
182+
"nullable": true
178183
}
184+
}
179185
}
180186
```
181187

182188
### Default to their type
183189

184-
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
190+
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
185191

186192
### Dependencies, DependentRequired, DependentSchemas
187193

@@ -198,36 +204,37 @@ Install via npm: `npm install json-schema-for-openapi`.
198204
And use as a Factory like:
199205

200206
```js
201-
const ConvertorFactory = require('json-schema-for-openapi')
207+
const ConvertorFactory = require("json-schema-for-openapi");
202208
const jsonSchema = {
203-
"$schema": "http://json-schema.org/draft-04/schema#",
204-
"title": "JSON API Schema",
205-
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
206-
"type": "object",
207-
"properties": {
208-
"errors": {
209-
"type": "object"
210-
}
211-
}
212-
}
213-
const convertedSchema = ConvertorFactory.convert(jsonSchema, 'main')
209+
$schema: "http://json-schema.org/draft-04/schema#",
210+
title: "JSON API Schema",
211+
description:
212+
"This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
213+
type: "object",
214+
properties: {
215+
errors: {
216+
type: "object",
217+
},
218+
},
219+
};
220+
const convertedSchema = ConvertorFactory.convert(jsonSchema, "main");
214221
```
215222

216223
which will output:
217224

218225
```json
219226
{
220-
"schemas": {
221-
"main": {
222-
"title": "JSON API Schema",
223-
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
224-
"type": "object",
225-
"properties": {
226-
"errors": {
227-
"type": "object"
228-
}
229-
}
227+
"schemas": {
228+
"main": {
229+
"title": "JSON API Schema",
230+
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
231+
"type": "object",
232+
"properties": {
233+
"errors": {
234+
"type": "object"
230235
}
236+
}
231237
}
238+
}
232239
}
233240
```

‎package-lock.json

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "json-schema-for-openapi",
3-
"version": "0.4.1",
3+
"version": "0.4.2",
44
"description": "Converts a regular JSON Schema to a compatible OpenAPI 3.0.X Schema Object",
55
"keywords": [
66
"json",

0 commit comments

Comments
 (0)