spectral:asyncapi warn off by default

asyncapi-tag-description

Tag object must have "description".

Applies to
description
Selects
$.tags[*]
Function
truthy
Specs
AsyncAPI 2.x

Use it

This rule ships with OpenLint in spectral:asyncapi. It's off by default, so turn it on by name:

extends: spectral:asyncapi
rules:
  asyncapi-tag-description: true

Definition

As defined in @openlint/openlint-rulesets. Functions show by name.

asyncapi-tag-description:
  description: Tag object must have "description".
  recommended: false
  formats:
    - AsyncAPI 2.x
  given: '$.tags[*]'
  then:
    field: description
    function: truthy

About this rule

Tags alone are not very descriptive. Give folks a bit more information to work with.

tags:
  - name: "Aardvark"
    description: Funny-nosed pig-head raccoon.
  - name: "Badger"
    description: Angry short-legged omnivores.

If your tags are business objects then you can use the term to explain them a bit. An ‘Account’ could be a user account, company information, bank account, potential sales lead, or anything. What is clear to the folks writing the document is probably not as clear to others.

tags:
  - name: Invoice Items
    description: |+
      Giant long explanation about what this business concept is, because other people _might_ not have a clue!

Sources