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.

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

An example configuration:

rules:
  tags-alphabetical: error

Examples

Given this configuration:

rules:
  tags-alphabetical: error

Example of incorrect tags:

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

Example of correct tags:

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

Related rules

• tag-description
• operation-description
• configurable rules

Resources

• Rule source
• Tags docs