# tag-description-defined

Source: https://api-genie.dev/docs/linter/asyncapi/rules/tag-description-defined

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

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).

Turn the rule off if the tag names are self-explanatory.

## Configuration

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

**Configuration example**.

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

## Examples

**Good**.

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

**Bad**.

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