spectral:oas warn off by default

tag-description

Tag object must have "description".

Applies to
description
Selects
$.tags[*]
Function
truthy
Specs
OpenAPI 2.0OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2

Use it

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

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

Definition

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

tag-description:
  description: Tag object must have "description".
  recommended: false
  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