Further clarifying the behaviour of overrides with referenced schemas

[liamnichols]

Describe the bug

I'm trying to use the overrides feature to disable a rule for a set of components that haven't yet been migrated but I appear to be unable to do so.

To Reproduce

Based on the example included as part of #2127:

Example:

Given the following 2 YAML documents

# my-document.yaml
openapi: "3.1.0"
paths: {}
components:
  schemas:
    User:
      $ref: "./User.yaml"

# User.yaml
title: ""
type: object
properties:
  id:
    type: string
required:
  - id

Configure an override like so:

overrides:
  - files:
      - my-document.yaml
    rules:
      empty-title-property: off

While running, spectral lint my-document.yaml, this would work, but if I added any JSONPath expression to the file, it stops working. For example:

overrides:
  - files:
      - my-document.yaml#/components/schemas
    rules:
      empty-title-property: off

Expected behavior

Empty title from referenced schema to be ignored

Environment (remove any that are not applicable):

• cli: 6.3.0
• OS: macOS 12

Additional context

I guess this is related to the issue described in the caveat, but it is confusing to me because while - my-document.yaml would work, - my-document.yaml#/ does not.

The problem that we face is that we run spectral on the root document, and not individually, but because our document has a lot of refs, this caveat prevents us from leveraging the override behaviour.

Are there any other workarounds other than having to run spectral lint for every single file?

Thanks!

[liamnichols]

After re-reading this line:

Please bear in mind that overrides are only applied to the root documents. If your documents have any external dependencies, i.e. $refs, the overrides won't apply.

I guess it describes exactly my problem. But it feels confusing to me still in the example above.

[P0lip]

Hey @liamnichols.
Would you be eager to tweak that part of the documentation?
I'm happy to help in case something is still unclear. :)