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.

[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.

[darrelmiller]

@JWMB That is a fair criticism. The lack of communication was definitely not because we don't care. It is just hard to make firm commitments on OSS projects at Microsoft that are not part of a primary effort.

[jscarle]

@darrelmiller I've sadly seen this as a recurring pattern from Microsoft. We all respect and understand that priorities don't always align with the community's priorities, and I believe I can comfortably say that most of us are able to adjust to that reality when it's communicated to us.

I really value that Microsoft has moved to doing a lot of it's work out in the open using GitHub, but there's still a lot of internal communication that never gets transmitted back to the community. For example, System.CommandLine was dead for years, stuck in a perpetual state of beta, to which no one responded and was suddenly bought back to life recently. This left most of us in the state of uncertainty wondering if it was a priority issue or if it was abandonware.

A small sign of life is often all that's needed for us to adjust our expectations.

[zijianhuang]

@jscarle, I share the same view, however, I guess the embarrassing situation is probably partly due to the reshuffle of MS, says, the recent massive layoff, so dedicated veteran programmers in MS might have to resolve some issues due to some temp vacuum. 3.1 had been release in early 2021, and many there have been many on .NET solution around for years. I am pretty sure veteran programmers in MS well understand what the communities along with business customers of MS stacks really want and need, and wishfully they may have more says in the priority.

[mkidsc1603]

The current ChatGPT Plugin only supports OAS 3.1

[msolujic]

hi @darrelmiller @MaggieKimani1
thank you for the recent clarification on priority level for this project in MS
do you guys have any news on this, is there a chance this support is finalised some time soon?

[cremor]

Somewhere in the ASP.NET Community Standup: OpenAPI Updates in .NET 9 video it was mentioned that .NET 9 will not contain OpenAPI 3.1 support because OpenAPI.NET will not be ready in time. So don't expect a release before mid November.

[lucassklp]

@cremor yes i checked the video and this is the moment they say it.

https://www.youtube.com/live/XoMese9g8WQ?feature=shared&t=3780

That's sad. This discussion started in 2022 and and two years after we don't have it.

[alexheat]

@MaggieKimani1 is there an ETA to add 3.1.0 support? Also, why is the issue marked as Closed if it is not supported yet?

[JWMB]

@darrelmiller @baywet I see the milestone due date has been changed to 2024-10-31 - is this the current assessment?
I think many of us would greatly appreciate if you could post in this thread when the milestone date has been updated. Thanks

[JWMB]

@darrelmiller @baywet @MaggieKimani1
Would be nice with some type of communication here. Any comment on the milestone date having been passed? Thanks.

[MaggieKimani1]

@darrelmiller @baywet @MaggieKimani1 Would be nice with some type of communication here. Any comment on the milestone date having been passed? Thanks.

Hi @JWMB, the preview release is currently underway. I'll let you know as soon as the preview is available on NuGET.