Skip to content

"Operation must have non-empty "tags" array" (operation-tags)

Last checked and updated

A linter found an operation (a get, post and so on under a path) that has no tags key, or has tags: []. The document is valid: in OpenAPI 3.0 and 3.1 tags is not a required field of the Operation Object. The message is a warning from the Spectral rule operation-tags. The fix is one line per operation: add a tag.

A file that produces it

missing.yaml: the first operation has no tags key, the second has an empty array.

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
  description: Orders of a shop.
  contact:
    name: API team
    url: https://example.com/support
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.example.com
tags:
  - name: orders
    description: Orders of the shop.
paths:
  /orders:
    get:
      operationId: listOrders
      description: All orders.
      responses:
        "200":
          description: The orders.
  /orders/{orderId}:
    get:
      operationId: getOrder
      description: One order.
      tags: []
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The order.
$ apigit lint missing.yaml
missing.yaml
  19:9   warn   operation-tags  Operation must have non-empty "tags" array.  (paths./orders.get)
  29:12  warn   operation-tags  Operation must have non-empty "tags" array.  (paths./orders/{orderId}.get.tags)

2 problems (0 errors, 2 warnings, 0 info, 0 hints)

The path at the end tells the two cases apart. When the key is missing it ends at the operation (paths./orders.get, line 19, the get: line). When the array is empty it ends at .tags (line 29, the tags: [] line).

The same file with openapi: 3.0.3 (and the license given by url, as 3.0 has no identifier) gives the same two lines: the rule does not depend on the version.

The fix

Give each operation a tag:

  /orders:
    get:
      operationId: listOrders
      description: All orders.
      tags:
        - orders

With both operations tagged orders:

$ apigit lint fixed.yaml
No problems found.

Why a linter asks for it

The specification describes the field as "A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier." (3.0.4 and 3.1.1, Operation Object). An operation without a tag has no group to appear under; what a documentation tool then does with it is up to that tool.

Cases and fixes

In the operationWhat the lint above reportsFix
no tags keyoperation-tags, path ends at the operationadd tags with one name
tags: []operation-tags, path ends at .tagsput a name in the array
tags: [""]not operation-tags; operation-tag-defined insteaduse a real name
tags: [Orders], root declares ordersoperation-tag-definedsame spelling and case in both places
tags: [orders], no root tags at alloperation-tag-defineddeclare the tag at the root, or switch that rule off

Two of these rows are worth a closer look.

An empty string passes. With tags: [""] on the first operation, operation-tags said nothing: the array is not empty. The finding came from another rule:

$ apigit lint emptystring.yaml
emptystring.yaml
  23:11  warn   operation-tag-defined  Operation tags must be defined in global tags.  (paths./orders.get.tags.0)

1 problem (0 errors, 1 warning, 0 info, 0 hints)

A rule set with operation-tag-defined switched off would not report that operation at all.

Fixing one warning can produce the next. Adding tags: [orders] to the operations of a file that has no tags list at the root trades one rule for the other:

$ apigit lint noroot.yaml
noroot.yaml
  20:11  warn   operation-tag-defined  Operation tags must be defined in global tags.  (paths./orders.get.tags.0)
  29:11  warn   operation-tag-defined  Operation tags must be defined in global tags.  (paths./orders/{orderId}.get.tags.0)

2 problems (0 errors, 2 warnings, 0 info, 0 hints)

The specification does not ask for this: "Not all tags that are used by the Operation Object must be declared" (3.0.4 and 3.1.1, the tags field of the OpenAPI Object). It is a second Spectral rule. Declaring the tag at the root, as missing.yaml does in lines 14 to 16, satisfies it and gives the group a description.

Switching the rule off, or making it an error

In the Spectral rule set the linter reads (.spectral.yaml in the working directory):

extends: ["spectral:oas"]
rules:
  operation-tags: off
$ apigit lint missing.yaml
No problems found.

With operation-tags: error in the same place, the two findings become errors and the run fails:

$ apigit lint missing.yaml
missing.yaml
  19:9   error  operation-tags  Operation must have non-empty "tags" array.  (paths./orders.get)
  29:12  error  operation-tags  Operation must have non-empty "tags" array.  (paths./orders/{orderId}.get.tags)

2 problems (2 errors, 0 warnings, 0 info, 0 hints)
error: lint failed: findings at severity error or above

In CI

With the default rule set the warning does not fail the run: apigit lint missing.yaml exited 0 above. Without changing the rule set, --fail-severity warn makes any warning fail it:

$ apigit lint missing.yaml --fail-severity warn
...
2 problems (0 errors, 2 warnings, 0 info, 0 hints)
error: lint failed: findings at severity warn or above

That run exited 1.

Related

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish