OpenAPI v3.1 Support

[philsturgeon]

Hello everyone! As the maintainer of openapi.tools I'm interested in tracking progress towards supporting OpenAPI v3.1.

It's got a bunch of amazing changes in it, solving problems like the the JSON Schema <!=> OpenAPI Schema Object divergence, and fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, and I see that some folks are starting to use it as they're getting problems #148. We need the tooling to catch up, and its been over a year now. Just in case folks didn't notice, I'm here to give a friendly prod!

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/

If you say you'll be working on it I can update openapi.tools to reflect that.

Let me know if you have any questions, or if you need any help with the upgrade process.

[cebe]

Support of OpenAPI 3.1 in this library heavily depends on cebe/php-openapi. Progress of that is tracked here: cebe/php-openapi#128

[cebe]

If you say you'll be working on it I can update openapi.tools to reflect that.

@philsturgeon please update openapi.tools status for thephpleague/openapi-psr7-validator and cebe/php-openapi to WIP.

[philsturgeon]

@cebe done, thanks for the update!

[tomasbreffitt]

With #185 merged, can we get a tagged release?

[scaytrase]

released as 0.19

[pieterocp]

We can probably close this now that #185 has been merged and released.

[Tim-Haboldt]

Am I correct in understanding that OpenAPI v3.1 is now largely supported, with the exception of the "unevaluatedProperties" keyword?

[philsturgeon]

@Tim-Haboldt depends very much of what you mean by that. Any tool using a compliant JSON Schema tool will support unevaluatedProperties through validation or similar, but a lot of documentation tools might not know how to show that (or various other new things).

A tool like this validator really should support it, and there should be a JSON Schema floating around in PHP land that brings support for it in "free".

[monitaurus]

Hi @philsturgeon, I saw that openapi.tools state that thephpleague/openapi-psr7-validator is compatible with OpenAPI 3.1.

I look at the cited PR #185 that seems to make think that the whole package where now 3.1 compliant.
The PR change the vendor cebe/php-openapi, in favor of @DEVizzent's fork and merged by @scaytrase, as the support for 3.1 seems stale.

But by reading the cebe/php-openapi first sentences in readme:

Read and write OpenAPI 3.0.x YAML and JSON files and make the content accessible in PHP objects.

It also provides a CLI tool for validating and converting OpenAPI 3.0.x Description files.
But there is only OpenAPI objects and validation of the description, no traces of data validation here.

And by reading some PR like #203, it seems that thephpleague/openapi-psr7-validator may have OpenAPI 3.1 objects but does not apply OpenAPI 3.1 specification.

[monitaurus]

I dug a bit deeper into the project, and found out indeed that despite the use of OpenAPI 3.1 objects to carry the specification, the validation itself doesn't have a full support of 3.1.

The validation of schema was built for OpenAPI 3.0, therefore a similar but not full valid JSON Schema object. There was an attempt with #185 to migrate to 3.1, but the full compliance with JSON Schema bringing the multi types is incompatible with the current architecture of the repo.

For example, an operation with a schema like below, will fail its validation against an integer 2.

{
    "type": [
      "string",
      "integer"
    ],
    "maxLength": 2
}

By looking at the SchemaValidator::validate, it validates keywords like type, items, maxLength, ... one by one, one after the other, independently of each other. Meaning that for the example above, the validation of the keyword type will be ok, but maxLength will fail, despite the type integer being allowed.

An idea to fix the repo and make it closer to OpenAPI v3.1, at least for the schema validation, is to ditch the whole homemade JSON schema validation from the project in favor of an existing one. The rest of the repo itself is well-made and can act as a bridge between PSR-7 messages and the new validator.

According to Bowtie, the only PHP package available for JSON Schema draft versions from "Draft 7" to "Draft 2020-12" is opis/json-schema.

I'll keep digging and try to find out if it's possible to replace prior validation with opis/json-schema.