spectral-rulesets 1.19.0 breaks path $ref behavior

[jstuckey]

Describe the bug

Using a $ref keyword under a path http verb started producing an error in version 1.19.0 of the spectral-rulesets package:

error  oas3-schema  Property "$ref" is not expected to be here.     paths./<some_path>.<some_verb>.$ref

This behavior is not present in spectral-rulesets 1.18.1 and earlier.

To Reproduce

1. Given this OpenAPI document

openapi: 3.0.3
info:
  title: Foo
  version: 1.0.0
  description: Foo API
  contact:
    name: Foo
tags:
  - name: FooTag
servers:
  - url: https://example.com
    description: Example

paths:
  /foos:
    get:
      $ref: 'foo_request.yaml'

# foo_request.yaml
description: Get a list of foos
summary: List Foos
operationId: foosIndex
tags:
  - FooTag
responses:
  "200":
    description: A collection of foos
    content:
      application/json:
        schema:
          type: object
          properties:
            foos:
              type: array
              description: The list of foos
              items:
                type: string

2. Run this CLI command

npx spectral lint openapi.yaml

3. See error

openapi.yaml
  16:9  error  oas3-schema  "get" property must have required property "responses".  paths./foos.get
 17:13  error  oas3-schema  Property "$ref" is not expected to be here.              paths./foos.get.$ref

Expected behavior

Using version 1.18.1 of the spectral-rulesets package produces the expected behavior:

No results with a severity of 'error' found!

Environment (remove any that are not applicable):

• Library version: 6.11.1
• OS: macOS Ventura

Additional context

If I had to hazard a guess, I suspect this change to be the culprit: #2574

[jstuckey]

The spec explicitly says that the path item object supports $ref while the operation object does not. I'm guessing that is why the setup I've described above is now considered invalid.

Still, the OpenAPI rendering tools I've used (Redoc, GitLab) handle this setup, and Spectral previously allowed it. It caught me off guard that our OpenAPI doc suddenly failed to lint.

[afmhenry]

Running into this issue as well. I think it is fair that $refs are resolved when determining if the contents of a schema are valid.

It makes using reusable servers, externalDocs, and other parts of OAS definitions standard and I don't want to disable that rule (as it is usually helpful :) )

I eventually bundle the OAS document, resolving these, but spectral is the initial linting tool to make sure we can bundle it all up.

[afmhenry]

8df2c36#diff-a4b02cdf70d6d4ff86a25b14f73e37f38cb47807de5ed4018c5384ed74d5a14fR682

If this was not set to "resolved": false, I believe the issue would have been avoided

[pedrosmr]

We're also experiencing this issue since the update to spectral-rulesets 1.19.0. Our OpenAPI 3.1 spec uses $ref under path extensively.

Considering this simplified example:

# base openapi.yaml
openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: Example API description
paths:
  /greetings:
    $ref: greetings.yaml
tags:
  - name: User
    description: Info about users
servers:
  - url: https://example-url.com
    description: Example server

# greetings.yaml
get:
  description: Get a greeting
  operationId: getGreeting
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Hello there!

The error we're seeing is:

error oas3-schema "~1greetings" property must not have unevaluated properties. paths./greetings

This issue is causing significant disruption for our development team and CI pipelines. We cannot pin the spectral-rulesets version due to the way it's installed, and we rely heavily on the oas3-schema rule for validation. Disabling the rule isn't the most viable option for us as we don't want to lose its functionality.

Is there a recommended workaround or a plan to address this in an upcoming release?

[xaben]

This is broken for us as well, we use same structure as mentioned by @pedrosmr

[evgeniy-solaris]

Confirm pedrosmr issue, absolutely the same case.

[realFranco]

Hello, right now I do not have a clear example.

As @afmhenry explained:

"$refs are resolved when determining if the contents of a schema are valid"

That helps to me.

Please, verifiy if the object created follow the OAS rules, in that way the schema to be referenced can be indexed through $ref.

[fab-mindflow]

New to spectral but we also use $ref extensively for modularity within paths and operations, and it fails with this error.
Any update since this has been raised?

[fluz]

Hi, does anyone have any updates or a workaround for this?

[fluz]

Hi all, I created a fix for this issue. Let's wait for the maintainers to take a look. 🙏🏾

And now I fixed the tests, let's wait #2844

[Theshedman]

Hi all, do you have any updates on this yet? I am currently experiencing the same $ref errors from Spectra linting. We extensively use $ref to modularize our OpenAPI 3.1 documents.