Add comprehensive OpenAPI 3.1 support with JSON Schema 2020-12 validation

[corbinbs]

Overview

This PR adds comprehensive support for OpenAPI 3.1, including JSON Schema 2020-12 validation and all major features introduced in the OpenAPI 3.1 specification. The implementation ensures proper handling of the enhanced schema validation capabilities while maintaining backward compatibility.

Key Features Added

1. JSON Schema 2020-12 Support

• Added Draft202012Validator for validating OpenAPI 3.1 schemas
• Created custom validators extending this for both request and response validation
• Implemented fallback mechanisms for draft2020_format_checker for compatibility

2. Type Arrays Support

• Added support for type arrays (e.g., type: ["string", "null"]) to replace the deprecated nullable: true property
• Updated validation logic to handle type arrays correctly

3. New JSON Schema Keywords

• Added support for direct keyword usage (e.g., exclusiveMinimum as a value rather than a boolean)
• Implemented validation for unevaluatedProperties

4. Webhook Support

• Added webhook parsing to the OpenAPI31Specification class
• Implemented property accessors for webhooks
• Added comprehensive tests for webhook definitions

5. Minimal Documents

• Added support for documents without paths (valid in OpenAPI 3.1)
• Added tests for minimal valid document configurations

6. PathItems in Components

• Added support for the new pathItems in the Components Object
• Implemented reference resolution for path item components
• Added tests to verify proper handling of referenced path items

7. Enhanced Security Features

• Added support for mutualTLS security scheme
• Implemented handling for security requirements with scopes arrays

8. Updated Example Application

• Enhanced the example application to demonstrate all new OpenAPI 3.1 features
• Added improved documentation highlighting the OpenAPI 3.1 capabilities

Testing

• Created comprehensive test suites covering all OpenAPI 3.1 features
• Added specific tests for edge cases and compatibility
• Ensured all existing functionality remains working (all tests pass)

Documentation

• Updated documentation to cover the new OpenAPI 3.1 features
• Enhanced example applications with clear instructions for using new capabilities

References

• OpenAPI 3.1.0 Release Notes
• JSON Schema 2020-12

Acknowledgments

This work was inspired by and builds upon the initial efforts in PR #1951 as well as the valuable insights provided in Issue #1396 comment. We want to ensure proper credit is given to those who contributed ideas and initial implementations that helped shape this enhancement.

[chrisinmtown]

Please say, will these changes automatically fix any of the open issues here related to allOf like #2031 ?

[corbinbs]

will these changes automatically fix any of the open issues here related to allOf like #2031 ?

@chrisinmtown - I'm not sure. I was just trying to see if I could get Claude Code to help me take some of the different issue comments and PR work related to OpenAPI 3.1 and put together something that might have a chance at landing to support folks looking to use Connexion with the 3.1 edition of the OpenAPI spec.

It is switching up validation if a 3.1 spec is used ... so it's possible there could be some different behavior now.
I'll make a TODO for myself to see what happens if I add some test scenarios like in #2018 to the new tests focused on OpenAPI 3.1 capabilities.