tags-unique (Swagger 2.0 linter rule)

tags-unique

Since 0.9.0 · fixed by --fix

This rule checks whether the tags in the root tags array of a Swagger 2.0 document have unique names, comparing names case-insensitively.

Rule Details

The Swagger 2.0 specification requires tag names to be unique. Tags whose names differ only in letter case are just as confusing: it is unclear whether they describe one group of operations or two.

The tags-unique rule reports Tag name is not unique (<name>) for each duplicate. Names are compared after converting ASCII letters to lower case. The issue normally points at the later duplicate; when the earlier tag has only a name and the later one has more properties, it points at the earlier tag instead.

The unique-tag check of the swagger-validation rule reports exact duplicates too, but it is disabled by default in favor of this rule.

Configuration

None.

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}
tags:
  - name: pets
  - name: users

Bad. Two tags differ only in letter case.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}
tags:
  - name: pets
    description: Operations on the pets of the shelter.
  - name: Pets
    description: Is this another tag, or a typo?

Automatic fixes

When invoked with --fix, the rule removes a duplicate tag from the root tags array when it is safe to do so:

a duplicate that has only a name is removed,
when the earlier tag has only a name and the later duplicate has more properties, the earlier tag is removed,
a duplicate whose properties other than name are equal to those of the earlier tag is removed.

Duplicates with different descriptions, external documentation or extensions are reported, but left for manual resolution.

When Not to Use It

We recommend to always enable this rule.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI documents are linted by the OpenAPI and AsyncAPI linters, which have their own tags-unique rules.