OpenAPI 3.1 support

[thernstig]

Is your feature request related to a problem? Please describe.
OpenAPI 3.1 was released a while ago. It would be nice if it was supported.

Describe the solution you'd like
Full OpenAPI 3.1 support.

Additional context
https://openapi.tools/ lists this tool as not having OpenAPI 3.1 support.

[essential-randomness]

Is there an update on this? What would it take to get it to work?

[essential-randomness]

I tried my hand at this and failed. See: #653

I don't think this is possible right now, but I'm waiting for help from the AJV folks to see if they can help figure out what I'm doing wrong (or whether there is an error in any of the libraries/specs). See: ajv-validator/ajv#1745

[JacobLey]

Hi, I've been jumping down 3.1 support hell and it looks like this issue is the source of truth for this feature?

In favor of forward progress, could this feature be split into separate features?

1. Updating AJV
2. Supporting 3.1

@essential-randomness PR has done a pretty good job spelling out the steps that are needed to update.

(The following discussion is only AJV related, so please let me know if you would rather I move this to a separate issue/discussion)

For my own benefit, it seems like this is the current situation (please correct me if I'm wrong)

1. This package currently depends on AJV v6.
2. AJV v6 natively supports drafts draft-04 - draft-07
3. Open API 3.1 uses draft 2020-12
4. AJV v8 (latest) supports drafts draft-06 - draft-2020-12 (small caveat for 04 support via ajv-draft-04)
5. The metaschema for OpenAPI 3.0 uses draft-04
6. Although OpenAPI 3.0 has their own JSON Schema subset this package uses draft-04

So to summarize, we definitely need to upgrade AJV to support 3.1, but doing so might break support for 3.0.

The PR linked above actually handles most of that I believe. It sounds like she ran into problems actually implementing 3.1, and not a blocker to updating AJV itself?

Support for draft-04 was implemented via the ajv-draft-04 package (which appears to use v8 under the hood).

(I was going to suggest an alternative of "forcefully" bumping to draft-07 but I believe usage of exclusiveMaximum is a relevant breaking change)

I'd be happy to try to take over the existing PR to refactor it as an AJV-only bump.

I believe that should be a non-breaking change? (MINOR version bump)

[essential-randomness]

I'd be very happy to have my PR picked up/used as inspiration! But it seems the issues I opened in the AJV repo haven't been closed yet, so I'm unsure what changed that made 3.1 work. Happy if that's the case, and looking forward to finally being able to use this library.

[JacobLey]

what changed that made 3.1 work

I'm not sure anything has? It sounds like the existing issue is with $dynamicRef, which isn't in use at all in 3.0

So this package should be able to bump to v8 safely. Actual 3.1 support is probably still blocked by that issue.

There is a suggested edit to the spec that might be a viable workaround ajv-validator/ajv#1573

I also tried to resolve the issue by tweaking the schema:

• Replacing "$dynamicRef": "#meta" by "type": [ "object", "boolean"] solves the issue.
• Replacing "$dynamicRef": "#meta" by "$ref": "#/$defs/schema" solves the issue as well. (when applied to the full OpenApi 3.1 schema this lets Ajv validate the full Petstore example as well)

But I think it would be easiest to implement and review by spitting that support from AJV bump

[seriousme]

Just a hint: OpenApi schema validator works around the issue in AJV by using a modified version of the official schema in which the $dynamic refs have been replaced. (see https://github.com/seriousme/openapi-schema-validator/blob/master/test/convert-3.1.js) This way it can still use AJV ;-)

The modified schema is available as: https://github.com/seriousme/openapi-schema-validator/blob/master/schemas/v3.1/schema.json

Hope this helps,
Hans

[thernstig]

@cdimascio @JacobLey looking at #713 it says it only partly solves this, not that it solves it completely. Can you re-open?

[JacobLey]

Agreed, 3.1 support should now be unblocked but is not yet implemented

Will hopefully get around to it in near future

[essential-randomness]

Thank you so much for your hard work! Looking forward to 3.1 support in the future!

[btisdall]

Yes, many thanks Jacob.

[gonenduk]

Hi,
Any updates on this?
Really appreciate your efforts here!

[nexsodev]

2 years later... will nothing be done?

[kennyma-eplus]

if-then-else schema is quite important now
hope express validator can upgrade to 3.1 soon

[ahmed1hsn]

I can contribute the changes regarding this migration.

[itai-gendler]

really need this please

[rgpro007]

Hello, any news on this support ?
It's already needed, and we had to skip express-openapi-validator...

[kennyma-eplus]

any replacement of express-openapi-validator ?
that need to support:
Open API 3.1 and ExpressJS

[Jackman3005]

From what I understand the core reason this library cannot support OpenAPI 3.1 is due to the underlying AJV library not yet supporting $dynamicRef features. This issue has been open on the AJV GitHub for awhile. I recently made a post and the suggestion still seems to be that express-openapi-validator should preprocess the spec and resolve dynamic references, as it is mentioned here.

Can someone confirm that they agree the support should be added to this library instead of AJV?

Does anyone else know if there are any other reasons holding back support for OpenAPI Spec v3.1?

[SF97]

Hello
I've made the PR #882 which should add support for OpenAPI 3.1, with @Jackman3005 suggestion. There are still tests missing, but I don't have a great amount of time to do them right now. I'm happy to take reviews/contributions to the PR to get OpenAPI 3.1 support as soon as possible :)

Happy 2024 everyone 🥳

[cdimascio]

Thanks a lot! I suspect this requires a bunch more work. It certainly requires tests.
Contributions welcome :)

I will plan to roll an alpha release, so folks can kick the tires on PR #882

[simonbetton]

Hello @cdimascio – any update on alpha release with PR #882 ?

[Jackman3005]

An Alpha release to test with would be great!

[patricktyndall]

Hoping this is merged soon!

[cdimascio]

The alpha release is available for testing. see comment in #882

also called out in the README

please provide feedback

[luisfidelis]

@cdimascio i submited a PR #1009 to also fix the ajv instance used in request validator.