tag-description-defined (AsyncAPI linter rule)

tag-description-defined

Since 0.9.0

This rule checks whether every tag of an AsyncAPI document has a meaningful description.

Rule Details

Documentation generators usually render tags as section headers, and their descriptions as the introduction of each section. A tag without a description leaves readers guessing what the grouped operations have in common.

The tag-description-defined rule checks every Tag object of the document, wherever it is defined: in info.tags, in the tags of servers, channels, operations, operation traits, messages and message traits, and in components/tags. It reports Tag '<name>' has no meaningful description defined for every tag whose description:

is missing, empty or blank,
is shorter than the configured minimal length,
is a placeholder: TODO, FIXME or TBD (case-insensitive).

Configuration

The configuration block is a positive integer: the minimal length of a description, in characters. The default value is 10.

Configuration Example.

version: "1.0"
commands:
  lint:
    asyncapi:
      rules:
        tag-description-defined: [warning, 20]

Examples

Good.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
  tags:
    - name: adoption
      description: Events related to adopting and returning pets.

Bad.

asyncapi: 3.0.0
info:
  title: Pet Events
  version: 1.0.0
  tags:
    - name: adoption
    - name: inventory
      description: TBD

When Not to Use It

You may disable this rule if the tag names are self-explanatory.

Compatibility