unused-shared-component

Since 0.9.0 · fixed by --fix

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.

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.

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:

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.