path-item-refs

It’s not un-common to use $ref pointers as Path Items. It’s technically allowed, but it’s not a great idea.

Why did this violation appear?

What you have done is not wrong, it’s just not great style. Avoid using $ref pointers as Path Items, use them for Operations instead. It’s generally easier to read and understand.

Bad example

Duplicate paths (different param names, but conflicting path definitions)

 paths:
  /pizza/{cake}/{icecream}:
    $ref: 'operations/pizza/cake/post.yaml'
  /pizza/{soda}/{candy}:
    $ref: 'operations/pizza/soda/get.yaml'  
  ...

Good example

paths:
  /pizza/{cake}/{icecream}:
    post:
      $ref: 'operations/pizza/cake/post.yaml'
  /pizza/{soda}/{candy}:
    get: 
      $ref: 'operations/pizza/soda/get.yaml'

How do I fix this violation?

Ensure all path params are used, they are unique and accounted for.

Spectral Equivalent

The rule is equivalent to path-params