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.

[philsturgeon]

Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.

OpenAPI v3.1 has a bunch of great little changes, solving problems like the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.

Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.

• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
• https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
• https://nordicapis.com/whats-new-in-openapi-3-1-0/

Here are some example files which can make for handy pass/fail test cases:

https://github.com/Mermade/openapi3-examples/tree/master/3.1

If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:

https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

Hopefully these links can help your contributors step up with confidence to help you get this project updated. If you do start getting pull requests towards OpenAPI 3.1 support, please send a pull request to openapi.tools with an issue tracking the progress, and folks will have a way to subscribe for updates.

LMK if you have any questions!

[santhosh-tekuri]

@fenollp you can easily compile schemas from openapi document using github.com/santhosh-tekuri/jsonschema/v5

here is the playground link that shows how to do it: https://go.dev/play/p/Hk077OKVi4e

[jamietanna]

Just as a quick nudge on this - this appears to be blocking folks doing contract testing using one of the libraries I maintain that depends on this.

I may start looking into this at some point to see if we can start getting - even if it's just partial - support for OpenAPI 3.1

[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-off]

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.