# ref-no-siblings

Source: https://apigenie.pl/docs/linter/openapi/rules/ref-no-siblings

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.12.0. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks that, in an OpenAPI 3.0 document, no property other than an extension sits next
to the `$ref` of a Reference Object.

## Rule details

In OpenAPI 3.0, an object with `$ref` is replaced by the object it refers to: any other property
next to `$ref` is ignored. A `description` or a `nullable: true` next to `$ref` does not apply:
the specification says to ignore it, and tools that follow it do so without a message. OpenAPI
3.1 allows a `summary` and a `description` next to `$ref` in a Reference Object, and any keyword
next to `$ref` in a schema. The rule checks 3.0 documents only: in 3.1 and 3.2 it does not report
the other keys a Reference Object ignores.

The rule reports `"<property>" next to $ref is ignored in OpenAPI 3.0` on each such property.
Specification extensions (`x-...`) are not reported. A Path Item Object's `$ref` is not checked:
OpenAPI 3.0 allows fields next to it. A `$ref` key in data is not a reference. Data are the
values of `example`, `default` and `enum`, of a schema's `examples` list, of an Example Object's
`value`, of a Link Object's `parameters` and `requestBody`, and of extensions. A YAML alias is
checked where its anchor stands, once.

Turn the rule off when every tool that reads the document applies the properties next to `$ref`.

To keep a description with a reference in 3.0, wrap the reference in `allOf`:

```yaml
Pet:
  description: A pet
  allOf:
    - $ref: '#/components/schemas/Animal'
```

## Examples

**Good**.

```yaml
openapi: 3.0.3
components:
  schemas:
    Pet:
      $ref: '#/components/schemas/Animal'
```

**Bad**. The description is ignored.

```yaml
openapi: 3.0.3
components:
  schemas:
    Pet:
      $ref: '#/components/schemas/Animal'
      description: A pet
```
