OpenAPI v3.1.0 Support

[lornajane]

User story.
As a user, I want to validate against the new version of openapi spec, e.g. while building support for webhooks. The spec isn't official yet though, so it might change and therefore so might the rule!

Is your feature request related to a problem?
I want to add OpenAPI 3.1.0 support to another tool I maintain and to my specs but if I do that, I can't validate them any more with Spectral.

Describe the solution you'd like
Support for new features, such as a draft custom ruleset or branch of spectral I could use (and offer feedback on, obviously)

Additional context
Spectral is great and your community loves you ❤️

[grische]

Here is the respective release for OpenAPI 3.1: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

Using the new JSON schema specification: https://json-schema.org/draft/2019-09/release-notes.html

[philsturgeon]

OpenAPI v3.1 will be rather tricky for Spectral to implement for a few reasons:

1. We use a meta-schema based validation approach and the OAS3.1 metaschema is not complete (First pass at 3.1 schema object meta-schema OAI/OpenAPI-Specification#2016)
2. We rely on AJV v6 for this validation. The WIP OAS v3.1 meta-schema is based on JSON Schema 2019-09, which was added in AJV v7, but AKV v7 dropped support Draft 04 which is required for OAS v3.0...

I had a few attempts at various solutions, such as running AJV v6 & v7 simultaneously with npm aliases, but that was a bit of a nightmare and wasn't going to work.

I've made a little progress over here: #1399 and we'll keep chipping away at this problem, whilst we help various dependencies upgrade and try to get a finalized meta schema sorted out.

We might split the work in two, just get Spectral working as expected for 3.1, then start making new rules for new features later, but I wanted to join up this thread and PR and give some context on what is taking a while.

[hilary]

Out of curiosity @philsturgeon , you say that the OAS v3.1 meta-schema is based on JSON Schema 2019-09, but the v3.1 spec says that the schema object is a superset of JSON Schema (Draft) 2020-12. What am I missing?

[philsturgeon]

Yep that’s correct. 2020-12 was just released and nothing supports it yet so aiming for 2019-09 gets us where we need to be.

[hver]

Bump: OAS v3.1 was released on 16 February: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

[philsturgeon]

Yes we were involved in the release of OpenAPI v3.1.

No need to bump the issue. It’ll be ready when it’s ready. Most tools don’t support it yet: https://OpenAPI.tools