Add support for OpenAPI 3.1

[jonathan-scholbach]

OpenAPI 3.1. makes the schema fully compatible with JSON schema. The library should provide support for it.

[takayamaki]

Continue from interagent/committee#352 (comment)

@geemus
I thought more about this with help from Claude Code.

Now, I think making fully separate classes for v3.0 and v3.1 is too much.
Instead, a progressive approach may work:

• Change classes under lib/openapi_parser/schemas/ and lib/openapi_parser/schema_validator/ to accept both v3.0 and v3.1 data shapes.
• Add a new class like OpenAPIParser::SpecValidator (name TBD) that checks whether the given document is v3.0-compliant or v3.1-compliant.
• Call OpenAPIParser::SpecValidator.run(root) in lib/openapi_parser.rb after reference expansion (L101).
  Warn or raise from there.
• Add a config option like strict_specification_version to OpenAPIParser::Config, accepting :silent / :warn / :raise.
• For the existing schema_validator, I think this can be absorbed by small is_a? branches on values received from schemas.
  (e.g. exclusiveMinimum is Boolean in v3.0 and Numeric in v3.1)

I will try this direction. Does it sound reasonable to you?

As a side note, about the small patch I already drafted:

Strictly speaking it does not follow the spec-aware approach above
— it accepts Components.pathItems even in v3.0 documents, where the specification does not allow it.
But practically it does no harm, and it unblocks real v3.1 documents that currently fail with MissingReferenceError:

paths:
  '/books':
    $ref: '#/components/pathItems/books_collection'
components:
  pathItems:
    books_collection:
      (snip)

Is it OK if I open a PR for this anyway?

[geemus]

That sounds reasonable so far, feel free to proceed to a PR.

[modosc]

@takayamaki i'm very interested in this - if this approach is seen as the correct one is it too soon to start on supporting 3.2? i'm happy to start on this if so.

[takayamaki]

@modosc Thanks for the interest.

I think that the approach was already accepted:
geemus approved it above, and the PRs implementing it (#191 through #208) are all merged.

I expect the new syntax in 3.2 can be handled in the same way.
Parse new fields permissively, and add SpecValidator rules to detect them in documents with an older version.
If the runtime behavior is simple, add SchemaValidator support too.

However, the maintainer is geemus, so this needs his go-ahead rather than mine.

One thing must be changed before that.
openapi_version is a Symbol now, and compared with ==.
So, a 3.2.0 document is treated as :unknown.
I will send a PR to make the version comparable (probably with Gem::Version).

@geemus what do you think?

[geemus]

@takayamaki sounds fine to me. I think the work so far has been going smoothly, so no reason (at least so far) to change course. Thanks for checking in on it and continuing to help us improve here.

[modosc]

awesome. i spent some time/tokens on this over the past week. i'll open a separate issue for 3.2 and we can move the discussion there.