# unused-shared-component

Source: https://api-genie.dev/docs/linter/asyncapi/rules/unused-shared-component

A rule of the AsyncAPI linter, which reads AsyncAPI 3 documents; the reader rejects AsyncAPI 2 documents. Since 0.9.0. Fixed by `--fix`. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks whether every shared component of an AsyncAPI document is
actually used.

## Rule details

Components that are never referenced make the document longer and harder to
maintain, and suggest that something is missing (for example, a message that
was defined but never attached to a channel).

The `unused-shared-component` rule checks every entry of every component
category: `schemas`, `servers`, `channels`, `operations`, `messages`,
`securitySchemes`, `serverVariables`, `parameters`, `correlationIds`,
`replies`, `replyAddresses`, `externalDocs`, `tags`, `operationTraits`,
`messageTraits`, `serverBindings`, `channelBindings`, `operationBindings` and
`messageBindings`. It reports `Unused shared component` for every component
that is not reachable from the rest of the document.

A component is reachable when a local `$ref` of the form
`#/components/<category>/<name>` (possibly pointing deeper into the
component, e.g. `#/components/schemas/Pet/properties/name`) appears anywhere
outside `components`, or inside another reachable component. References are
followed transitively, so a schema used only by an unused message is unused
as well. References nested in untyped values, such as bindings or payloads
in other schema formats, count too.

A component that has this rule disabled (see below) is always considered
used, and so is everything it references.

Turn the rule off for documents that serve as libraries of shared components, referenced from other
documents.

## Examples

**Good**. The message is used by the channel, and the schema by the message.

```yaml
asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
channels:
  petAdopted:
    address: pets.adopted
    messages:
      petAdopted:
        $ref: "#/components/messages/PetAdopted"
components:
  messages:
    PetAdopted:
      payload:
        $ref: "#/components/schemas/Pet"
  schemas:
    Pet:
      type: object
```

**Bad**. Nothing references the `PetReturned` message, so both the message
and the `Shelter` schema it uses are unused.

```yaml
asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
channels:
  petAdopted:
    address: pets.adopted
    messages:
      petAdopted:
        $ref: "#/components/messages/PetAdopted"
components:
  messages:
    PetAdopted:
      payload:
        $ref: "#/components/schemas/Pet"
    PetReturned:
      payload:
        $ref: "#/components/schemas/Shelter"
  schemas:
    Pet:
      type: object
    Shelter:
      type: object
```

To keep a component that is meant to be referenced from other documents,
disable the rule on it:

```yaml
components:
  schemas:
    Shelter:
      type: object
      x-lint-disable: [unused-shared-component]
```

## Automatic fixes

`--fix` removes all unused components. When
every entry of a component category is unused, the whole category map is
removed, so that no empty map is left behind.
