"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 operation | What the lint above reports | Fix |
|---|---|---|
no tags key | operation-tags, path ends at the operation | add tags with one name |
tags: [] | operation-tags, path ends at .tags | put a name in the array |
tags: [""] | not operation-tags; operation-tag-defined instead | use a real name |
tags: [Orders], root declares orders | operation-tag-defined | same spelling and case in both places |
tags: [orders], no root tags at all | operation-tag-defined | declare 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
- "Potentially unused component has been detected": another warning of the same rule set, with the same way to switch it off.
- Finding a broken $ref: an error, not a warning, from the same lint run.