Add OpenAPI 3.1 Support

[darrelmiller]

Includes:

• Add webhooks property to the root document #1046
• Adds a summary property in the info object #1039
• Add license SPDX identifier #1042
• Add reusable path items to components object #1056
• Add summary and description to OpenApiReference object #1077
• Add root property jsonSchemaDialect #1138
• Support the core and validation keywords from the latest JSON schema specification (JSON Schema Specification Draft 2020-12) #1275
• Add support for $schema, $id, $comment, $vocabulary, $dynamicRef, $dynamicAnchor, $recursiveAnchor, $recursiveRef #1274
• Map nullable to null type #1273
• Enable upcasting from V2/V3 to 3.1 #1272
• ExclusiveMinimum and ExclusiveMaximum change from type boolean to type number #1271

[felschr]

I'm particularly interested in the new prefixItems option from the JSON schema specification, which can be used for supporting tuples as arrays:
https://stackoverflow.com/questions/57464633/how-to-define-a-json-array-with-concrete-item-definition-for-every-index-i-e-a

[gregsdennis]

@darrelmiller do you have an ETA on this? Do you need help?

[darrelmiller]

It is currently planned as a stretch goal for CY2022H2.

[baywet]

I believe dictionary support is missing from the list microsoft/kiota#62

[KeithMAtFis]

One thing that i would like to see is support for readOnly on properties that are using $ref. for example

[gregsdennis]

@KeithMAtFis I have good news for you!

Previously, $ref meant that sibling keywords were ignored.

But since OpenAPI 3.1 uses JSON Schema 2020-12, this restriction is lifted, and now sibling keywords are respected.

Your use case should work as long as the package does something with the readonly annotation (I have no reason to believe it won't).

[KeithMAtFis]

@gregsdennis that is great. I should have provided some background, I am using Minimal API and DOTNet 6, C#10 and it seems that that does not support OpenAPI 3.1.0 yet in its current form. Out of the box there is Swagger support but it seems to only support 3.0.1 and backwards support to v2. I have not found a way to allow output to 3.1.0 standards.

The Nugets that I am using are Swashbuckle.AspNetCore, Swashbuckle.AspNetCore.Swagger and Swashbuckle.Core all at version 6.4.0 (latest). Would you know if there is another NuGet that I should be using or certain configuration i should use?

Btw, I really appreciate you taking the time to respond.

(here is the GITHUB link to support 3.1.0 in Swashbuckle domaindrivendev/Swashbuckle.AspNetCore#2349)

[gregsdennis]

I don't know of any others, no.

It looks like Swashbuckle is dependent upon this lib, so the goal is to get this one going first.

[gregsdennis]

There's a new project https://github.com/sourcemeta/alterschema that aims to convert between schema versions. I think they plan to handle OpenAPI versions as well eventually. This might take care of "Enable upcasting from V2/V3 to 3.1".

[mimse]

What are the timeline on these changes? It looks like a lot of project depends on this project to move forward with OpenAPI 3.1

With regards,
Morten

[funkeyfreak]

Hello all! I'm taking a sab at implementing the 9th item - "Map nullable to null type." I have broken up this effort into two seperate PRs. I want to make sure I am not stepping on anyones toes before raising a PR.

The first modifies the parser to map the OpenAPI represetntation of null within a type array to the existing nullable property. The second implements the more complex type array support required by the OpenAPI specification.

Does this sound good to everyone?

[baywet]

Hey @funkeyfreak,
We're happy to merge any PR coming our way.
Make sure you start your work from release/2.0.0 and target that branch when opening your pull requests.
And let us know if you have questions.

[MaggieKimani1]

@funkeyfreak we're considering taking a dependency on an external JSON schema library so maybe just hold off on creating a PR.

[TomBruns]

It looks a lot of progress is occurring to support this goal. Is there a general target on when OpenAPI v3.1 support will be released?

[zijianhuang]

Swagger/SmartBear has started to support 3.1 since June, at https://smartbear.com/news/news-releases/swagger-open-source-tooling-now-supports-latest-op/
And at the moment, the lib gives "Microsoft.OpenApi.Readers.Exceptions.OpenApiUnsupportedSpecVersionException : OpenAPI specification version '3.1.0' is not supported."

[msolujic]

hi all, do we have any update for this, any ETA, anything?

[MaggieKimani1]

Hi @msolujic
This work is set out to go with our 2.0 release early next year. We're working on a couple of breaking changes hence the hold up.

[HavenDV]

My research about OpenAPI 3.1 support led me to this project - https://github.com/gregsdennis/Graeae
Perhaps this will help someone right now, or will help with progress in this issue.

[gregsdennis]

@HavenDV I created that as kind of an experiment to see if I can make a JsonSchema.Net-based OpenAPI implementation.

It provides the models, and all of the referencing and everything works right, but it's really basic.

My focus is really the json-everything project that hosts the schema lib, and I don't really have time to put effort into Graeae right now.

[msolujic]

hi @MaggieKimani1
@zijianhuang @baywet

are we closer for this issue to be closed and OAS 3.1 to be supported by OpenAPI.NET?

[MaggieKimani1]

Hi @msolujic, we've finished working on this issue but we're currently working on other breaking changes that need to go out with the v2.0 release. ETA for the preview release is within a month or less.

[varmancholan]

Do we have support for OAS 3.1 now?