stoplightio / spectral-documentation

Teach Spectral how to help improve the quality of your OpenAPI-based documentation.
8 stars 4 forks source link

Should operation-tag-defined continue to exist? #6

Open philsturgeon opened 1 year ago

philsturgeon commented 1 year ago

I am curious about whether or not operation-tag-defined should be moved over here from spectral:oas, as it does not belong in the newer spectral-openapi ruleset.

Context

This is the old rule in spectral:oas:

    "operation-tag-defined": {
      message: "Operation tags must be defined in global tags.",
      description: "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.",
      recommended: true,
      given: "$",
      then: {
        function: oasTagDefined,
      },
    },

Current Behavior

Currently Spectral with the default spectral:oas ruleset will tell everyone that tags defined in operation must be defined in global tags, but OpenAPI v3.x says quite the opposite.

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.

Emphasis mine. Full quote here.

Expected Behavior

I think the spectral:oas ruleset lose this change, but I am not sure if it adds anything to have it in spectral-documentation.

Fundamentally, what does this add?

Possible Solution(s)

Do not add the rule here, and let it die when spectral:oas goes away.