OpenAPI 3.1.0 is coming

[danielgtaylor]

Maintainer EDIT: Want to see this move forward? Jump to this comment

First release candidate has been put up:

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

Creating this issue to track what work needs to be done to support it. Of particular interest is the section on breaking changes to align with JSON Schema 2019-09.

[fenollp]

My opinion is it'd be best to bring in https://github.com/xeipuuv/gojsonschema and switch on OpenAPI's version field to know when to translate an OpenAPI <v3.1 schema to the JSON Schema format that this project handles.

[kevin-postman]

I see this issue was closed and help is wanted. Now that 3.1.0 is released, are there plans to soon start adding support for 3.1.0? Is there any discussion outside of Issues that I can participate in to get involved?

[fenollp]

Hi Kevin, this issue is still open although was not discussed outside of issues as far as I'm aware.
I think the way to support 3.1 as well as solve all the validation issues is through a func (s *openapi3.Swagger) CompileSchemas() error which would convert our schema data to gojsonschema's and for (*openapi3.Schema) VisitJSON*(...) error funcs to use that.
That'll break today's usage but this lib is v0 anyway.

[fenollp]

Actually gojsonschema only Supports draft-04, draft-06 and draft-07. today.
I'm not finding any lib that supports the 2020-12 draft that OpenAPIv3.1 relies on.
I do think that the move to this lib needs to happen though and support for new JSON Schema drafts will eventually land in gojsonschema AFAIK.

Do you have needs for the newer Schema Drafts or are you mostly interested in the other OpenAPIv3.1 changes?

[kevin-postman]

Me personally, interested in 3.1 support. Obviously the sooner tools support 3.1 the better and a lot of tools are built on top of kin-openapi. So I would think this is a pretty important update to add to kin-openapi as soon as possible. If moving to gojsonschema is the future anyway, then perhaps moving to it now along with adding 3.1 support should be taken up.
My apologies on thinking it was closed.. I see that was a linked issue. :D.

[wolfeidau]

@fenollp have you had a look at https://github.com/qri-io/jsonschema as a possible alternative given it currently states it supports 2019-09 and is supposedly faster?

[fenollp]

Yes and I did see the benchmark mentioning it was less correct than the other lib. See https://github.com/wbvinc/go-jsonschema-validator-benchmarks
I did not verify this on my end however.

I haven't dug in deeper yet but will in the coming weeks. Thanks for the link.

[timbunce]

Not only does https://github.com/qri-io/jsonschema support 2019-09, it's also actively maintained.

In contrast, gojsonschema had a last commit in Oct 2020 and last release in Oct 2019. Re supporting 2019-09 the author said in March 2020:

Plans yes, but time no. The new specification also requires a thorough rewrite of all the internals in order to support things like $vocabulary and unEvaluatedProperties and the like and I haven't found the courage yet to start that project in my spare time.

The santhosh-tekuri/jsonschema repo has no commits since Feb and no sign of working towards supporting 2019-09.

I think qri-io/jsonschema is the only horse in the race at the moment. Adopting it, and contributing fixes as needed, seems like the most fruitful path.

[kevin-postman]

If moving to qri-io/jsonschema moves kin-openapi to accepting openapi 3.1.0 sooner, I am all in favor. The sooner those of us using kin-openapi can start adding support for 3.1.0 the better. Seems like one of the nagging issues since the inception of Swagger/OpenAPI is how long it takes tools to adopt/migrate to a new version. Maybe reaching out to the qri-io team and having a dialog with them regarding their commitment might ease the idea of replacing the recent work with gojsonschema?

[timbunce]

The santhosh-tekuri/jsonschema repo has no commits since Feb and no sign of working towards supporting 2019-09.

santhosh-tekuri/jsonschema v4.0.0 says "draft 2019-09 support".

I think qri-io/jsonschema is the only horse in the race at the moment.

Seems like it's now a two horse race.

[bojanz]

https://github.com/santhosh-tekuri/jsonschema now supports draft 2020-12, putting it ahead in the race.

[kevin-postman]

Is there any progress on 3.1 support? Wondering if anyone is working on it yet, or if not is there a plan to start work on it soon?

[fenollp]

I did some exploration in #412 but stumbled into roadblocks:

• https://pkg.go.dev/github.com/santhosh-tekuri/jsonschema/v4#Compiler
  • (*Compiler).AddResource and (*Compiler).Compile() both require filenames / URLs
  • meaning there is no easy way to map multiple components/schemas to a single openapiv3 document
• https://pkg.go.dev/github.com/qri-io/jsonschema?utm_source=godoc
  • does not provide a way to compile multiple schemas (components) into one struct so as to validate data. I.e. only schemas without any $ref could be used here.
• https://pkg.go.dev/github.com/xeipuuv/gojsonschema
  • I could get much farther with this lib but it is missing 2020-12 draft.
  • Note the kind of API that allows compiling multiple schemas into one: https://github.com/getkin/kin-openapi/pull/412/files?authenticity_token=GxG1YcyaLB5WDnr7mTjh%2BWM0Tf9JpnqTMWvb4%2B%2B783h8mxca7%2BMYuOQKYmGIqURO9tgePt7hOFeBkbecX%2Fe0Kw%3D%3D&file-filters%5B%5D=.go&file-filters%5B%5D=No+extension#diff-4f8cf6da8df120cafa1ded276fd61b3fceff3373dfb8ad5c8c5b8b05b33c4cfbR29-R36

Issues should be raised on respective repos, I just didn't come around to doing that yet.

[peteraba]

Just a little nudge for this issue:

• Map multiple components/schemas to a single openapiv3 document santhosh-tekuri/jsonschema#48
• Compile multiple schemas (components) into one struct qri-io/jsonschema#113
• Support for 2020-12 draft xeipuuv/gojsonschema#340

[kevin-postman]

Just following up to see if there is any movement on this issue? Any work in progress by anyone? Anytime soon maybe? 3.1 has been final for almost a year.. be good to see this project get a jump on it so Go projects depending upon it can start to support 3.1.

[fenollp]

Hi @kevin-postman and others,
I understand this issue (and some others) are pressing to some and would like to apologize for the less than stellar progress here.

I have been maintaining this project for a few years now and am looking to turn this into a more sustainable initiative.
Recently, I set up GitHub Sponsorship so if you'd like to support this project's future and preserve some of my mental health I encourage you to register for a monthly sponsoring here. A one-time donation can also help towards solving piecemeal issues.

Here's a tutorial from GitHub on how to find other maintainers that may need your help whose work you might depend on.

Regarding this specific issue, considering the large ramifications and attention to quality it entails, I would like to work on it once some funding has been promised or secured. We can discuss terms privately.

Licensing won't change due to sponsorship. All open source work will continue to be available to all and enjoyed equally by all members of the community.

TL;DR: Nothing changes and this continues being MIT licensed. Please consider Sponsoring.

[petkostas]

Nice to see this moving forward, support for 3.1 is getting increasingly painful (at least in the GOlang world) as lots of tools rely on this library at the moment.
Let us know how we can contribute and get this moving forward.

[SVilgelm]

I have played with the generics and created a small lib for openapi v3.1 https://github.com/sv-tools/openapi

Feel free to use it as an example

[philsturgeon]

This also seems like it might be handy. https://github.com/pb33f/libopenapi

[Ilyes512]

Any (progress) update on this subject? Not trying to put any pressure, but some more info might give us some insight going forward.

[jamietanna]

I've recently been chatting with @deepmap-marcinr around this with https://github.com/deepmap/oapi-codegen that we maintain.

I've looked at this a few times to start trying to pick up this, but have been a little overwhelmed by the amount of work it may lead to 😅 that may not be a fair assumption, but I've not got full appreciation of all the differences between versions.

@philsturgeon aside from the links above, do you have any reading / people that we may be able to chat to who've added support for 3.1 on top of 3.0?

I've planned to look through things like libopenapi ☝️ and others to see what sort of test data they've got that may give us an indication of how much needs to change in this library to support it.

I'm also considering seeing if folks fancy one-off sponsoring (not necessarily the $1000 option) work on this migration, as that may help with prioritising it.

[timbunce]

Bowtie is "a meta-validator for the JSON Schema specification" with test suites for multiple versions, including draft7, 2019-09, and 2020-12.

The results for draft7 include gojsonschema with 10 errors, and jsonschema with zero errors. The results for 2020-12 include only jsonschema with, again, zero errors.

[Ilyes512]

Is it important to keep supporting the older OpenApi implementations?

It might be easier to create a new version of this package (or a totally new one) that only starts supporting OpenApi from version 3.1, because you might be able to offload a larger part of the logic to an existing jsonschema package?

[deepmap-marcinr]

I think it will be time for a V2 branch once this happens. I never anticipated that V1 would become this popular, so let's say it's not the greatest piece of code ever written. I've learned many things from the last couple of years which it would be good to get into a V2 and shed some old compatibility issues.

…

________________________________________ From: Ilyes512 ***@***.***> Sent: Monday, April 24, 2023 3:14 AM To: getkin/kin-openapi Cc: Marcin Romaszewicz; Mention Subject: Re: [getkin/kin-openapi] OpenAPI 3.1.0 is coming (#230) Is it important to keep supporting the older OpenApi implementations? It might be easier to create a new version of this package (or a totally new one) that only starts supporting OpenApi from version 3.1, because you might be able to offload a larger part of the logic to an existing jsonschema package? — Reply to this email directly, view it on GitHub<#230 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ALKC5DC5FKE3T6A64SRB4EDXCZHARANCNFSM4OC32QXQ>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[jamietanna]

@deepmap-marcinr I think you may be talking about oapi-codegen not kin-openapi? 😁

[deepmap-marcinr]

Haha, indeed. Sorry, I got mailing lists crossed.

…

________________________________________ From: Jamie Tanna ***@***.***> Sent: Monday, April 24, 2023 1:19 PM To: getkin/kin-openapi Cc: Marcin Romaszewicz; Mention Subject: Re: [getkin/kin-openapi] OpenAPI 3.1.0 is coming (#230) @deepmap-marcinr<https://github.com/deepmap-marcinr> I think you may be talking about oapi-codegen not kin-openapi? 😁 — Reply to this email directly, view it on GitHub<#230 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ALKC5DG5YCM36LWCXI4TDY3XC3N5PANCNFSM4OC32QXQ>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[podhmo]

#230 (comment)

It might be easier to create a new version of this package (or a totally new one) that only starts supporting OpenApi from version 3.1, because you might be able to offload a larger part of the logic to an existing jsonschema package?

Indeed. As a smaller step, for example, creating an openapi31 directory and reimplementing everything might be a better flow?

As for creating new package, I honestly have mixed feelings about seemingly ignoring kin-openapi's excellent contributions.

[cletter7]

Is this being worked on or abandoned?

[excavador]

Any updates?

[Malix-Labs]

Seems like it's time to move to https://github.com/pb33f/libopenapi

[praneetloke]

I think @fenollp is pretty clear that he would like some support from the community in terms of sponsorship to take on this task. See this comment from him. It would be nice to lend him the support he is looking for especially given the fact that this library is used in so many different packages in the Go ecosystem.

[martimors]

Is it coming? 🤔

Edit: So many people here are users of Googles Apigee framework. I think it is unfortunate that this project gets a barrage of people complaining about OAS3.1 support missing, when this really should be a feature contributed by the Apigee maintainers for free, it's only fair given what they get out of this project for nothing. Just my opinion! At least let's not barrage the maintainers of FOSS.

[StevenACoffman]

Hey, this is a beloved and much-used library, and I appreciate all the hard work that has gone into it and I know everyone else reading this does as well.

If you are using it at your workplace, or are using one of the many popular libraries and applications that depends on it then please consider doing one of the following:

1. asking your own company to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment.

2. Using your company's vendor support system, report a support issue with your company's vendor that uses this library asking that vendor to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment. In no particular order: Grafana, Google (Apigee), Hashicorp, PingCap, Ory, Solo, Replicate, and all the blockchain companies that own the downstream.

3. Report a GitHub issue with one of the many company-owned popular libraries and applications that depends on this one asking their corporate sponsor to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment. Do not pester other individual unpaid volunteer maintainers of other open-source projects.

I have been maintaining this project for a few years now and am looking to turn this into a more sustainable initiative. Recently, I set up GitHub Sponsorship so if you'd like to support this project's future and preserve some of my mental health I encourage you to register for a monthly sponsoring here. A one-time donation can also help solve piecemeal issues.

Here's a tutorial from GitHub on how to find other maintainers that may need your help whose work you might depend on.

Regarding this specific issue, considering the large ramifications and attention to quality it entails, I would like to work on it once some funding has been promised or secured. We can discuss terms privately.

Licensing won't change due to sponsorship. All open-source work will continue to be available to all and enjoyed equally by all community members.

Just always remember:

[excavador]

Hey, this is a beloved and much-used library, and I appreciate all the hard work that has gone into it and I know everyone else reading this does as well.

If you are using it at your workplace, or are using one of the many popular libraries and applications that depends on it then please consider doing one of the following:

1. asking your own company to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment.

2. Using your company's vendor support system, report a support issue with your company's vendor that uses this library asking that vendor to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment. In no particular order: Grafana, Google (Apigee), Hashicorp, PingCap, Ory, Solo, Replicate, and all the blockchain companies that own the downstream.

3. Report a GitHub issue with one of the many company-owned popular libraries and applications that depends on this one asking their corporate sponsor to contribute code or sponsorship of fenollp for this upstream library kin-openapi to support OpenAPI 3.1 - see here OpenAPI 3.1.0 is coming #230 and specifically this comment. Do not pester other individual unpaid volunteer maintainers of other open-source projects.

I have been maintaining this project for a few years now and am looking to turn this into a more sustainable initiative. Recently, I set up GitHub Sponsorship so if you'd like to support this project's future and preserve some of my mental health I encourage you to register for a monthly sponsoring here. A one-time donation can also help solve piecemeal issues.

Here's a tutorial from GitHub on how to find other maintainers that may need your help whose work you might depend on.

Regarding this specific issue, considering the large ramifications and attention to quality it entails, I would like to work on it once some funding has been promised or secured. We can discuss terms privately.

Licensing won't change due to sponsorship. All open-source work will continue to be available to all and enjoyed equally by all community members.

Just always remember:

Thank you for notice. Meanwhile, we switched from using this library to Huma Framework.

I would have warmly supported your initiative one year ago, two years ago, but not today.

You comment a little bit late

[StevenACoffman]

@excavador :

Thank you for notice. Meanwhile, we switched from using this library to Huma Framework.

Everyone's glad you found a solution that works for you. I hope you and your company learned to sponsor the developers of your new choice of open-source software and its dependencies to keep them maintained.

[praneetloke]

@excavador "You comment a little bit late" is unfair and a bit short-sighted in my opinion.

I would have warmly supported your initiative one year ago, two years ago, but not today.

@fenollp edited the issue description back in Jan 2022, more than a year before your first comment (in Dec 2023) stating "Any updates?" when it was clear that support from the community was requested. It's not just you though and am not accusing any individual specifically of ignoring the support request. I understand not everyone has the means to support financially as an individual but if your company is benefiting from an open-source project, you should strongly advocate for supporting it financially.

Thank you for notice. Meanwhile, we switched from using this library to Huma Framework.

FYI, perhaps you know this already but this issue was opened by @danielgtaylor who created Huma framework. Huma also has a sponsors section.

In the end, replies such as "I switched to another library because this maintainer is xyz to implement abc..." are not helpful at all. Feel free to switch and add the alternate library to https://github.com/getkin/kin-openapi?tab=readme-ov-file#alternatives if you wish.

[excavador]

@StevenACoffman @praneetloke

Hello,

It seems like I did not explain properly what I meant, and you have an incorrect impression or did not understand what point I am trying to make.

It's all about expectation management and proper community communication.
Every single personal contributor or engineer has limited resources - and limited time.
Even in the case of a company, the company also has limited resources and money.

This issue has stayed in the state "common soon" for the last two years.
It's impossible to make any decision of planning in the current state of the issue.
People are waiting, asking "when?", because they rely on this library.

In our case, in December 2023, I considered the cost of upgrading this library to 3.1 by myself or my company's engineers.
In general, I declined this idea because of the following:

• I could observe long-standing issues and Pull Requests without reaction for weeks
• I could see, that this is not a simple task which requires a lot of changes

Meanwhile, "Huma" was in a state where it was too risky to choose Huma. I did post-pone of decision to the feature, even in situation where my product were already suffering from lack of OpenAPI 3.1 support

During the Summer of 2024, I reconsidered the state again. We need OpenAPI 3.1 already, and Huma contributor and maintainer, make amazing communication with community

• fast Pull Request Acceptance
• proper communication with issues
• expectation management - even in case when he was going to vacation - like "I will not answer to question the next two weeks"

This issue of kin-openapi was in the state "coming soon," with many questions, such as "any updates?" without any answer.
It was the impression that the project was dying, first of all - because of a lack of communication.

As a result, we spent around 30,000 euros to migrate to Huma; meanwhile, Huma is not perfect. Also, my engineers created around 15 issues and 10 pull requests with fixes for Huma, and the author of Huma carefully worked with his own community.

In these situations, I have zero doubts about contributing my personal time or company time and money to Huma because the maintainer of Huma is responsible.

Even the current comment—"project needs support"—is okay, guys. But what about the plan? What about the estimation of the work? What about the timeline and roadmap?

This part of communication to the community is heavily broken by kin-openapi maintainers, and BECAUSE OF THAT, I prefer to invest time and money of myself and my company in Huma instead of kin-openapi.

It is NOT about "support-less" from my side or company side.
It is NOT about "we are using it for free without any help from our side"

It is all about proper COMMUNICATION and EXPECTATION MANAGEMENT from both sides.
Request like this one year ago will led me to question "could you please explain, how much money or work you need and how we could help you?"
But right now the resources (money & engineer time) which I am as manager of company could invest to kin-openapi was already invested to other things

• migration of product to Huma
• contribution to Huma from our company side

I am not blaming anybody! I just explain the ratio of decision making, and why exactly I did not see kin-openapi as the good investment.
It is not about "I am greedy", it is about "it will be bad investment" - because of the broken communication to community.

With best regards, Oleg

[StevenACoffman]

@excavador Thanks for explaining your reasoning, as your prior comment came across as unhelpful. I'm glad you and your company are contributing back to Huma and are able to collaborate with the community to the benefit of all.

Be kind to volunteer maintainers and not feel entitled to their free future work. My lesson from the past few years was to be proactive as a maintainer in asking for community help early, and to try to contribute back generously on whatever I depend on that I'd like to see continue.

[excavador]

@excavador Thanks for explaining your reasoning, as your prior comment came across as unhelpful. I'm glad you and your company are contributing back to Huma and are able to collaborate with the community to the benefit of all.

Be kind to volunteer maintainers and not feel entitled to their free future work. My lesson from the past few years was to be proactive as a maintainer in asking for community help early, and to try to contribute back generously on whatever I depend on that I'd like to see continue.

Glad, that we clear the air and understand each other!