tags-unique

Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error

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 raise the same question: 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.

The OpenAPI and AsyncAPI linters have rules of the same name, tags-unique and tags-unique.

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.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        tags-unique: off

Related rules

Further reading

Was this helpful?