spectral:asyncapi warn off by default

asyncapi-3-tag-description

Tag object must have "description".

Applies to
description
Selects
$.info.tags[*]
Function
truthy
Specs
AsyncAPI 3.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-3-tag-description: true

Definition

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

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

About this rule

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

info:
  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.

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

Sources