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?