# OpenAPI Tags
Source: https://speakeasy.com/openapi/tags

import { Table } from "@/mdx/components";



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 for OpenAPI v3.0-v3.1.

<Table
  data={[
    { field: "`name`", type: "String", required: "✅", description: "The name of the tag. **_Must_** be unique in the document." },
    { field: "`description`", type: "String", required: "", description: "A description of the tag. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description." },
    { field: "`externalDocs`", type: "[External Documentation Object](/openapi/external-documentation)", required: "", description: "Additional external documentation for this tag." },
    { field: "`x-*`", type: "[Extensions](/openapi/extensions)", required: "", description: "Any number of extension fields can be added to the tag object that can be used by tooling and vendors." }
  ]}
  columns={[
    { key: "field", header: "Field" },
    { key: "type", header: "Type" },
    { key: "required", header: "Required" },
    { key: "description", header: "Description" }
  ]}
/>

## 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. The upcoming OpenAPI v3.2 introduces a new `tags.summary` to pass the human-friendly same 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)

In OpenAPI v3.2 there will be two new properties which can be used to handle 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 uses are `nav` for Navigation, `badge` for visible badges, `audience` for APIs used by different groups. A [registry of the most commonly used values](https://spec.openapis.org/registry/tag-kind/) is available.

It will look something like this.

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

  - 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
```

This is not available yet, but will be coming in OpenAPI v3.2 which many tooling providers are excited to start supporting.

## 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.