tags-alphabetical

Ensures that all tag name fields in the tags object are listed in alphabetical order. Note that this rule does not automatically sort your tags if they are not in alphabetical order. The rule only produces a warning or an error, and expects you to modify your API descriptions.

OAS Compatibility
2.0 ✅
3.0 ✅
3.1 ✅

API design principles

Information architecture is important. Among other benefits, it improves the efficiency and speed with which people discover information in the resources you provide. When deciding how to organize tags in your API descriptions and documentation, you can try different approaches through tree testing (we did some tree testing on Redocly documentation navigation). However, sometimes it's easier to keep things simple, and go alphabetical. If you've already decided to alphabetize, this rule keeps it alphabetized.

We've been here and it's ugly:

X: "Can't you see it's in alphabetical order?"

Y: "Can't you talk to me like an adult?"

X: "Don't adults know the alphabet?"

This rule is intended to prevent bikeshedding and diffuse tension between teammates (could be renamed to peacemaker).

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).
ignoreCase boolean Possible values: true, false. Default false (in recommended configuration).

An example configuration:

Copy
Copied
rules:
  tags-alphabetical: error

Examples

Given this configuration:

Copy
Copied
rules:
  tags-alphabetical: error

Example of incorrect tags:

Copy
Copied
tags:
  - name: Partner APIs
  - name: External APIs
  - name: Testing APIs
  - name: Central Management APIs

Example of correct tags:

Copy
Copied
tags:
  - name: Central Management APIs
  - name: External APIs
  - name: Partner APIs
  - name: Testing APIs

Related rules

Resources