Operation tags in global tags element

[rartych]

Problem description

Spectral linting rule operation-tag-defined produces warnings for qod-api.yaml like this:

  Message :   Operation tags must be defined in global tags.
  Rule    :   operation-tag-defined
  Path    :   paths./sessions.post.tags.0
  Line    :   88

Expected behavior Tags should be defined in a top-level tags element

Alternative solutions

1. Removing tags from operation objects in qod-api.yaml

2. Exclusion of this rule from future ruleset for CAMARA APIs as tags element is not required by OAS

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#fixed-fields

A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.

Additional context Spectral default OAS ruleset includes also:

openapi-tags-alphabetical

OpenAPI object should have alphabetical tags. This will be sorted by the name property. Recommended: No

tag-description

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. Recommended: No

[hdamker]

@rartych Is there a guideline from Commonalities if operation tags should or should be not used? Are other sub projects using operation tags?

[rartych]

API Design Guidelines says that for each HTTP method (i.e operation) definition should include:

Tag list to classify methods.

In the global tag element each tag can have description and externalDocs property.

For further discussion on tags usage and style see: Commonalities issue #80