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 all 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 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. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The named tag MUST exist in the API description,

This interacts with the following text in 3.1.1:

For resolving component and tag name connections from a referenced (non-entry) document, it is RECOMMENDED that tools resolve from the entry document, rather than the current document. This allows Security Scheme Objects and Tag Objects to be defined next to the API’s deployment information (the top-level array of Server Objects), and treated as an interface for referenced documents to access.

However, that was written to resolve Operation Object tags fields to Tag Objects, which means you need to locate a particular OpenAPI Object with Tag Objects under its tags field. For this parent field, if we follow the same guidance, a Tag Object in a referenced document would search for its parent in the entry document.

Resolving to the entry document would be the most consistent thing, but not necessarily the most intuitive.

On the one hand, making parent only resolve within the current document feels more intuitive. On the other hand, it's also limiting if for some reason you wanted to break tags across multiple OpenAPI Documents in a single OpenAPI Description, and it would make two fields that reference via a tag name behave differently, which is confusing as well.

A third option that ends up being more problematic than it seems at first would be to make parent take a URI-reference, but since the OpenAPI Object's tags field is an array, JSON Pointers end up being cryptic and fragile.

A fourth option, which would be annoyingly complex, would be to offer both parent (resolves to the entry document, since that could be different if the same other document is reference from multiple entry documents) and parentRef (like operationRef) which could be used with a URI-ref, e.g. #/tags/4.

A fifth option would be to define plain name fragments for tags, e.g "tag.{tagname}" so that URI-references would not have to have a numerical index. But we've avoided doing that sort of thing (although JSON Schema's $anchor keyword does it).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm playing around with writing up a tagRefs field to allow tags to resolve by URI, and if that works out then maybe parentRef would be the consistent option.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're in agreement here, although perhaps the wording needs work. An OpenAPI description has the tags defined in its entry document, because there's nowhere else to define them. They don't need to be refs, because like the info section, tags are a document-level thing and I don't see how they can be ref'd in. Operations can use tags that are not defined, but if the tag is defined and has a parent, then I think that parent should be defined too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but if the tag is defined and has a parent, then I think that parent should be defined too.
+1

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lornajane I agree with the decision to merge this, and I'll pick up the subtleties elsewhere since I need to do so for tags in the Operation Object.

This gets tricky when you have multiple OpenAPI Documents (capital D) in your OAD, each of which can have a list of Tag Objects. Similar problems exist for the Security Requirement and Security Scheme Objects.

| <a name="tag-kind"></a>kind | `string` | 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. |

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