Skip to content

Additional fields for the tag object #4288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 16, 2025
Merged

Additional fields for the tag object #4288

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f822af7
Add more fields to the tag object, from the proposal
lornajane Jan 3, 2025
d3d8633
Better formatting of examples
lornajane Jan 3, 2025
a055eca
Improve tag kind wording and link registry
lornajane Jan 10, 2025
581391a
Typo
ralfhandl Jan 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 42 additions & 7 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2687,24 +2687,59 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="tag-name"></a>name | `string` | **REQUIRED**. The name of the tag. |
| <a name="tag-name"></a>name | `string` | **REQUIRED**. The name of the tag. Use this value in the `tags` array of an Operation. |
| <a name="tag-summary"></a>summary | `string` | A short summary of the tag, used for display purposes. |
| <a name="tag-description"></a>description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
| <a name="tag-external-docs"></a>externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. |
| <a name="tag-parent"></a>parent | `string` | The `name` of a tag that this tags is nested under. The named tag MUST exist in the API description, and circular references between parent and child tags MUST NOT be used. |
| <a name="tag-kind"></a>kind | `string` | A machine-readable string to categorize what sort of tag it is. Common uses are `nav` for Navigation, `badge` for badges, `internal` for internal APIs, but any string value can be used. |

This object MAY be extended with [Specification Extensions](#specification-extensions).

##### Tag Object Example

```json
{
"name": "pet",
"description": "Pets operations"
}
"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"
}
]
```

```yaml
name: pet
description: Pets operations
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
```

#### Reference Object
Expand Down
Loading