search

stoplightio / spectral

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.
https://stoplight.io/spectral
Apache License 2.0
2.5k stars 238 forks source link

OAS Core Rule: $ref can have description and summary siblings #2480

Closed CanVuralStudocu closed 1 year ago

CanVuralStudocu commented 1 year ago

Describe the bug I think according to the OpenAPI spec (https://swagger.io/specification/#reference-object) reference objects can have $ref, summary and description fields. But the Spectral rule no-$ref-siblings marks the description sibling of $ref as error.

To Reproduce

  1. Given this OpenAPI/AsyncAPI document 
    {
    "$ref": "#/components/schemas/Pet",
    "description": "This is a sibling description that should be allowed."
}
  2. Run this CLI command spectral lint
  3. See error no-$ref-siblings $ref must not be placed next to any other properties

Expected behavior description and summary should be allowed as a sibling to $ref

davidkeaveny commented 1 year ago

https://swagger.io/docs/specification/using-ref/#sibling suggests otherwise:

Any sibling elements of a $ref are ignored. This is because $ref works by replacing itself and everything on its level with the definition it is pointing at.

Instead, you have to use allOf:

{
  "allOf": [
    { "$ref": "#/components/schemas/Pet" }
  ],
  "description": "This is a sibling description that should be allowed."
}
CanVuralStudocu commented 1 year ago

I found this issue that confirms $ref can have siblings: https://github.com/OAI/OpenAPI-Specification/issues/2744

mnaumanali94 commented 1 year ago

@CanVuralStudocu That's an addition to the OAS3.1 spec. This rule as configured doesn't apply to OAS3.1 and is only enabled for OAS3 and 2