# unused-shared-component

Source: https://apigenie.pl/docs/linter/asyncapi/rules/unused-shared-component

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.

## Configuration

None.

## 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

When invoked with `--fix`, this rule 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.

## When Not to Use It

You may disable this rule for documents that serve as libraries of shared
components, referenced from other documents.

## Compatibility

This rule is compatible with AsyncAPI 3.x documents. AsyncAPI 2.x documents
are rejected by the reader and are not linted.