# Tags in OpenAPI best practices

# OpenAPI Tags

Tags are a way of grouping operations for various purposes, like creating more sensible navigation in API documentation, defining API lifecycle status with tags like "Beta" that can be filtered out later, or something else entirely.

## Tags Object

The document-level `tags` field is an optional field, which is a list of objects describing each
[tag](/openapi/tags#tag-object). Tags have at bare minimum a `name`, but can have a `description`, point to `externalDocs`, and potentially have some `x-*` extension properties.

```yaml
tags:
  - name: drinks
    description: The drinks endpoints.
  - name: authentication
    description: The authentication endpoints.
```

Tags can then referenced by [operations](/openapi/paths/operations), with an array allowing multiple tags to be referenced.

```yaml
paths:
  /drinks:
    get:
      operationId: listDrinks
      tags: [drinks]
```

Here is the full specification for the Tag Object.

## Human-friendly or machine-friendly

Whether a tag should be human readable (e.g. `Publishing Tokens`) or machine-friendly (e.g.: `publishingTokens`) has been a long source of discussion in the OpenAPI world, but consensus is forming around machine-friendly tags more like variable names, in whatever format is preferred: PascalCase, camelCase, snake_case.

Then the human friendly name can be passed in one of two locations.

1. For OpenAPI v3.0 and v3.1 users, the commonly used vendor extension `x-displayName` will work in most API documentation tools.
2. OpenAPI v3.2 introduces a new `tags.summary` field to pass the human-friendly name.

Check to see which of these keywords are supported by documentation tools in the toolchain, and if neither perhaps go with a human-readable `name` until that tool supports `x-displayName` or the OpenAPI is upgraded to v3.2.

## Grouping Tags

Tags are used for grouping operations, but sometimes its necessary to group tags, especially in larger APIs with hundreds (or even thousands) of operations.

```yaml
tags:
  - name: stores
    x-displayName: Stores
  - name: inventory
    x-displayName: Inventory
  - name: employees
    x-displayName: Employees

x-tagGroups:
  - name: Store Management
    tags:
      - stores
      - inventory
  - name: Human Resources
    tags:
      - employees
```

Operations are then assigned to tags as normal. Tools which understand `x-tagGroups` like [Scalar](https://scalar.com) and [Redoc](https://redocly.com/) will use them to create the nested navigation structures, and tools which do not understand the keyword will build the flat list of operations.

```yaml
paths:
  "/stores":
    get:
      operationId: get-stores
      summary: Get Stores
      tags:
      - stores

  "/inventory":
    get:
      operationId: get-inventory
      summary: Get Inventory
      tags:
      - inventory

  "/employees":
    get:
      operationId: get-employees
      summary: Get Employees
      tags:
      - employees
```

In Scalar the above example would look like this.

![Screenshot of Scalar interpreting tag groups](/assets/openapi/guide/scalar-x-tagGroups.png)

OpenAPI v3.2 adds two new properties for handling tag grouping and nesting:

- `tags.parent` - The `name` of a tag that this tag is nested under. The named tag must exist in the API description, and circular references between parent and child tags must not be used.
- `tags.kind` - A machine-readable string to categorize what sort of tag it is. Any string value can be used; common values are `nav` for navigation, `badge` for visible badges, and `audience` for APIs used by different groups. A [registry of commonly used values](https://spec.openapis.org/registry/tag-kind/) is available.

The `kind` field enables tooling to differentiate between tags used for navigation and tags used for other purposes, such as badges or audience segmentation.

```yaml
tags:
  - name: account-updates
    summary: Account Updates
    description: Account update operations
    kind: nav

  - name: beta
    summary: Beta
    description: Operations that are in beta
    kind: badge

  - name: partner
    summary: Partner
    description: Operations available to the partners network
    parent: external
    kind: audience

  - name: external
    summary: External
    description: Operations available to external consumers
    kind: audience
```

## Best practices

### Always define tags before referencing them

It's allowed for operations to reference undefined tags (tags not defined in the document-level `tags`, but it is recommended that all tags used are defined here to provide useful documentation and intent for the tags.

### Alphabetize tag definitions

Some documentation tools will automatically alphabetize them, some will not, so to make sure they are alphabetized for all documentation tools put them in that order in the OpenAPI document.