XSD to JSON Swagger 2.0 or open API 3.0

[michaelgrudgings]

We are converting from swagger 2.0 to open API 3.0. I can't seem to figure out how to get the XSD to JSON generator to set up the schema in 3.0. Any ideas how to do this?

[florin_nica]

Hi Michael,

OpenAPI 3.0 uses an extended subset of JSON Schema Specification, meaning that some keywords are supported and some are not, or they have slightly different usage than in JSON Schema. The XSD to JSON Schema tool will generate a JSON Schema file that is one of Draft 4, 6, 7, Draft 2019-09, or Draft 2020-12, but it may not be OpenAPI 3.0 fully compatible. Unfortunately, you cannot set it up in any way.

However, if you convert the XSD file to a Draft 2020-12 JSON Schema, you will get full compatibility for OpenAPI 3.1. Hope this helps!

Regards,
Florin

[michaelgrudgings]

Draft 2020-12 is not an option in my drop down. How do I add that?

[florin_nica]

Hi Michael,

I forgot to mention that the conversion to Draft 2020-12 is available starting with the version 25.0.0 of the add-on, only for Oxygen XML Editor 25. This release of the XSD to JSON Schema add-on is scheduled for the next week. I will send you a notification when it is ready to install.

Regards,
Florin

[florin_nica]

Hi Michael,

Just wanted to let you know that version 25.0.0 of the XSD to JSON Schema add-on has just been released, and the conversion to Draft 2020-12 is now available. Make sure you are using Oxygen XML Editor 25.

Regards,
Florin

[michaelgrudgings]

Thanks for the update. Excited to try it out!

[michaelgrudgings]

We're running into an issue where when we add our openAPI 3.0 endpoint to a 2020-12 drafted JSON schema, the keywords (schema, anyOf, and defs) aren't allowed?
Would anyone happen to have an example of an openAPI3.0 endpoint combined with a 2020-12 drafted JSON Schema for reference?
"$defs": {
"Carrier": {
"type": "object",
"required": [
"carrierID",
"carrierName"
]

defs#.PNG (14.57 KiB) Viewed 4664 times

[florin_nica]

Hi Michael,

First of all, if you need JSON Schema Draft 2020-12 for defining your endpoints, I think the best solution is to migrate from OpenAPI 3.0 to 3.1.0. You can check this post for more details: https://www.openapis.org/blog/2021/02/1 ... 0-to-3-1-0.

On the other hand, I see that you are trying to use a JSON Schema document for referencing its definitions from the OpenAPI document. Writing the entire JSON Schema at the end of the OpenAPI document is not the way to go. Instead, you can add the definitions into the "components" object, something like this:

Code: Select all

"openapi": "3.x.x",
"info": {},
.
.
.
"components": {
    "schemas": {
        "Carrier": {
            "type": "object",
            "required": [
                "carrierID",
                "carrierName"
            ]
        }
    }
}

Then you can simply refer this definition from anywhere in the OpenAPI document by using its pointer (i.e. "#/components/schemas/Carrier"). Hope this helps!

Regards,
Florin