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)?

[fluz]

@katepol I tried, but I will check again who can support us on this :-/

[mikehaertl]

@tomek-tursa-sb @tekyu you both seem to have privilege to approve and merge PRs. Could you please have a look here? It's open for 6 months without any feedback from the team.

If you don't want to merge: Who's the right person to contact?

[fluz]

@tomek-tursa-sb @SB-rohitdesai @tekyu @mattshaner can you support us and take an eye on this PR 🙏🏾

[NelDev1104]

@tomek-tursa-sb @SB-rohitdesai @fluz We should close this PR, I dont think we should change the oas/v3.1, the oas json is the official ruleset from openapi. Looking into the latest oas schema version the $ref properties got added in paths and was missing in the current version. A new issue should be created to update the oas/v3.1. I can create a PR for it

[fluz]

@tomek-tursa-sb @SB-rohitdesai @fluz We should close this PR, I dont think we should change the oas/v3.1, the oas json is the official ruleset from openapi. Looking into the latest oas schema version the $ref properties got added in paths and was missing in the current version. A new issue should be created to update the oas/v3.1. I can create a PR for it

@NelDev1104, I couldn't find the changes in your link, the $ref property doesn't seem to be added in the paths as you mentioned.

Maybe I'm looking in the wrong place. Could you please clarify where the difference is?

[NelDev1104]

@fluz
https://spec.openapis.org/oas/3.1/schema/2021-09-28 Current spectral OAS Version

    "paths": {
      "type": "object",
      "patternProperties": {
        "^/": {
          "$ref": "#/$defs/path-item"
        }
      },
      "$ref": "#/$defs/specification-extensions",
      "unevaluatedProperties": false
    },
    "path-item": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "servers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/server"
          }
        },
        "parameters": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/parameter-or-reference"
          }
        }
      },

Oas 3.1 latest version

    "paths": {
      "$comment": "https://spec.openapis.org/oas/v3.1#paths-object",
      "type": "object",
      "patternProperties": {
        "^/": {
          "$ref": "#/$defs/path-item"
        }
      },
      "$ref": "#/$defs/specification-extensions",
      "unevaluatedProperties": false
    },
    "path-item": {
      "$comment": "https://spec.openapis.org/oas/v3.1#path-item-object",
      "type": "object",
      "properties": {
        "$ref": {
          "type": "string",
          "format": "uri-reference"
        },
        "summary": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "servers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/server"
          }
        },
        "parameters": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/parameter-or-reference"
          }
        },

In the current version $ref is missing in the properties path-item

[fluz]

@fluz https://spec.openapis.org/oas/3.1/schema/2021-09-28 Current spectral OAS Version

    "paths": {
      "type": "object",
 ...
          "items": {
            "$ref": "#/$defs/parameter-or-reference"
          }
        },

In the current version $ref is missing in the properties path-item

Nice 😍 , thanks for the clarification.

Feel free to close this one and open a new one. But I think the most important thing is to have this issue solved 😢.