feat(rulesets): improve OAS 3.1 external references validation by fluz · Pull Request #2844 · stoplightio/spectral

fluz · 2025-08-20T15:12:50Z

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

- Update OAS 3.1 schema to better support external references - 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 issues with external reference validation in OpenAPI 3.1 documents.

fluz · 2025-09-08T15:59:20Z

Hi someone can review my proposal.

TIA

fluz · 2025-09-22T00:39:39Z

Hi Pals,

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

fluz · 2025-10-15T11:59:05Z

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

fluz · 2025-11-13T23:13:24Z

@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 · 2025-12-04T16:10:59Z

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 · 2025-12-12T14:15:16Z

Hi @stoplightio/oss-spectral

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

Thanks in advance

katepol · 2026-01-29T15:50:22Z

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

fluz · 2026-02-07T17:55:18Z

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

mikehaertl · 2026-02-19T15:53:37Z

@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 · 2026-03-02T09:59:21Z

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

NelDev1104 · 2026-03-24T09:12:10Z

@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 · 2026-03-24T09:57:19Z

@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 · 2026-03-24T10:21:15Z

@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 · 2026-03-24T11:08:10Z

@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 😢.

mikehaertl · 2026-05-21T10:45:20Z

So what is the state of this problem? Is it solved somehow? I still have this error.

slegarraga

Good test coverage for OAS 3.1 external $ref on paths — harness scenario + unit case both document the expected “no false schema errors” behavior.

Small surface area in validators; aligns with #2899. Looks good from my side.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for validating OpenAPI 3.1 documents that use external $ref at the Path Item level, and introduces regression coverage in both the test harness and unit tests.

Changes:

Added a new OAS 3.1 scenario that lints a document with an external Path Item $ref.
Updated the OAS 3.1 JSON Schema for paths entries to allow a Path Item or a reference.
Added a unit test ensuring an OAS 3.1 document with an external Path Item $ref does not produce schema errors.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
test-harness/scenarios/oas3.1/external-ref.scenario	New integration-style scenario validating external Path Item `$ref` passes linting.
packages/rulesets/src/oas/schemas/oas/v3.1/index.json	Schema change to permit reference-style Path Items under `paths`.
packages/rulesets/src/oas/tests/oas3-schema.test.ts	Regression test for OAS 3.1 external Path Item `$ref` acceptance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@@ -0,0 +1,40 @@
+====test====
+OAS 3.1 - External Ref Validation 


      "patternProperties": {
        "^/": {
-          "$ref": "#/$defs/path-item"
+          "$ref": "#/$defs/path-item-or-reference"


fluz marked this pull request as ready for review August 20, 2025 15:13

fluz requested a review from a team as a code owner August 20, 2025 15:13

fluz marked this pull request as draft August 20, 2025 15:13

fluz force-pushed the fix/oas31-external-ref-validation branch from a7c06e7 to fde1451 Compare August 20, 2025 15:23

fluz marked this pull request as ready for review August 20, 2025 15:27

This was referenced Aug 20, 2025

fix(rulesets): allow external references in OAS 3.1 paths #2843

Closed

spectral-rulesets 1.19.0 breaks path $ref behavior #2655

Open

Merge branch 'develop' into fix/oas31-external-ref-validation

d3a60b4

Merge branch 'develop' into fix/oas31-external-ref-validation

5c4a7fb

Merge branch 'develop' into fix/oas31-external-ref-validation

2ff4fea

Merge branch 'develop' into fix/oas31-external-ref-validation

be6166a

slegarraga approved these changes May 23, 2026

View reviewed changes

Merge branch 'develop' into fix/oas31-external-ref-validation

1aabb9a

Copilot AI review requested due to automatic review settings May 23, 2026 20:19

Copilot AI reviewed May 23, 2026

View reviewed changes

		@@ -0,0 +1,40 @@
		====test====
		OAS 3.1 - External Ref Validation

Uh oh!

Conversation

fluz commented Aug 20, 2025

Uh oh!

fluz commented Sep 8, 2025

Uh oh!

fluz commented Sep 22, 2025

Uh oh!

fluz commented Oct 15, 2025

Uh oh!

fluz commented Nov 13, 2025

Uh oh!

olvlvl-solaris commented Dec 4, 2025

Uh oh!

fluz commented Dec 12, 2025

Uh oh!

katepol commented Jan 29, 2026

Uh oh!

fluz commented Feb 7, 2026

Uh oh!

mikehaertl commented Feb 19, 2026

Uh oh!

fluz commented Mar 2, 2026

Uh oh!

NelDev1104 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fluz commented Mar 24, 2026

Uh oh!

NelDev1104 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fluz commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mikehaertl commented May 21, 2026

Uh oh!

slegarraga left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

NelDev1104 commented Mar 24, 2026 •

edited

Loading

NelDev1104 commented Mar 24, 2026 •

edited

Loading

fluz commented Mar 24, 2026 •

edited

Loading