Add OpenAPI 3.1 Support

[darrelmiller]

Includes:

• [ ] Add root property webhooks
• [x] #1039
• [x] #1042
• [ ] Add pathItems object to the component object
• [ ] Add support for Summary/Description properties alongside Reference Objects
• [ ] Add root property jsonSchemaDialect
• [ ] Support the core and validation keywords from the latest JSON schema specification (JSON Schema Specification Draft 2020-12)
• [ ] Add support for $schema, $id, $comment, $vocabulary, $dynamicRef, $dynamicAnchor, $recursiveAnchor, $recursiveRef
• [ ] Map nullable to null type
• [ ] Enable upcasting from V2/V3 to 3.1
• [ ] ExclusiveMinimum and ExclusiveMaximum change from type boolean to type number

[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 https://github.com/microsoft/kiota/issues/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 https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/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?

[JWMB]

I'm confused by the lack of communication here, especially given that so many projects are dependent on this library (and that the 3.1 spec was released >3 years ago). It seems from comments on other issues that the v2.0 release will be the one where 3.1 is supported?

2.0 is past due by about 1 month. What's the current ETA? Will you release a preview?

[msolujic]

joining questions from @JWMB

hi @MaggieKimani1 @zijianhuang @baywet do we have any ETA when support for 3.1 will be released?

[MaggieKimani1]

Hi @JWMB, @msolujic thank you for your patience. We incurred a couple of issues during testing that set us back in terms of the release timeline. We're still working on getting a v2.0-preview out as soon as possible so please bear with us.

Cc: @darrelmiller @coseguera @njaci1

[JWMB]

Great, thanks. Please consider keeping us updated on the progress - I suggest keeping the the milestone page updated with the latest info, plus adding a link to it from any issues/comments asking about the release or support for 3.1.

[baywet]

@njaci1 we've had comments about lack of clear communications multiple times at this point. Can you please:

• log any issue found during testing (if not already the case)
• add them to the milestone.
• update the milestone due date with a new tentative date.

This way the community, customers, and dependant teams have a clearer understanding of where things are at.

Thanks!

[JWMB]

The commit history (pretty much only lib bumps lately) and the lack of communication gives me the feeling this project is abandonware. and that the real work is being done somewhere else in preparation for the .NET 9 release (which has several OpenAPI initiatives tied to it). Hidden git branches could be another possibility.

I can't imagine the Kiota team would be content with having dependencies to this project if vnext is really progressing as slowly as it seems.

[darrelmiller]

@jwmb ...or let us consider another theory. A big chunk of the dev team has been asked to work on security related issues. The remaining developers are being asked to focus on some specific Copilot related activities because it is a company wide effort that takes the highest priority. The few people who were tasked with working on this library are only able to sneak in a few hours a week, at least while this other work takes priority. Imagine that the target was to actually deliver 3.1 support as part of the .net9 timeline, but that the team had to tell the .net team that they were not able to make that deadline. Why? Because OpenAPI 3.1 is hard to implement properly. Partly because the integration between JSON Schema 2020-12 and OpenAPI 3.1 was sadly underspecified. I can take partial blame for that as I was heavily involved. Many other OpenAPI libraries treat $refs as pre-processing instructions and the in-memory representation has no awareness of use of $ref. That's not how OpenAPI.NET works. OpenAPI.NET attempts to preserve the referencing model whilst still trying to make the referenced information easily accessible. This has been challenging in OpenAPI.NET v2, particularly whilst trying to incorporate the JsonSchema.NET library which comes with its own set of conventions and behavior.
So, please consider for a moment, that maybe there isn't some grand schema to secretly replace this library with some hidden effort that has a team of devs dedicated to doing things in the dark. Consider maybe that we do not hear a lot of customer demand for 3.1 and that developers have been temporarily assigned to work on what we believe is currently higher priority.

[JWMB]

Fantastic to finally get some honest messaging, I'm sincerely thankful. I think if you look at past comments here, the main issue is the lack of communication; silence breeds speculation. This definitely helps me make decisions on how to proceed with some of my projects. Would have been good if I had been able to make them earlier, but I can cut my losses and move on.