feat(rulesets): improve OAS 3.1 external references validation

[fluz]

Fix schema validation error where path items were incorrectly flagged as having unevaluated properties. Changed paths pattern properties to use path-item-or-reference instead of path-item to support external references in OpenAPI 3.1 specifications properly.

Fixes the issue where documents like:

paths:
  /greetings:
    $ref: 'greetings.yaml'

Would generate: "~1greetings" property must not have unevaluated properties.

• Update OAS 3.1 schema to use path-item-or-reference for paths
• Add external references test scenario in test-harness
• Update Arazzo schema validators to use improved OAS 3.1 schema
• Enhance OAS 3 schema test coverage

Fixes #2655

Checklist

• Tests added
• Docs added

Does this PR introduce a breaking change?

• Yes
• No

[fluz]

Hi someone can review my proposal.

TIA

[fluz]

Hi Pals,

just a kindly reminder to not forget my PR 🙏🏾 :-)

[fluz]

Hi @mnaumanali94 , can you please take a look on this PR when you have time 🙏🏾 :-)

[fluz]

@bcoughlan @frankkilcommins

Could you please take a look at my PR? 🙏🏾
Btw, the code isn’t passing at the moment because I just merged the develop branch into my branch. Previously was everything right :-)

Thanks!

[olvlvl-solaris]

Thank you @fluz for providing a fix for this issue. The $ref keyword is indeed allowed for Path Item Object as stated in the following document: https://learn.openapis.org/referencing/overview.html#a-taxonomy-of-references. Maybe your fix will be merged just in time for Xmas :)

[fluz]

Hi @stoplightio/oss-spectral

Please take a look when it is possible in this PR. 🙏🏾

Thanks in advance

[katepol]

@fluz did you consider requesting a review personally (not from the whole team)?