diff --git a/src/oas.md b/src/oas.md index a54e56835b..4f025228b4 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2691,24 +2691,59 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object | Field Name | Type | Description | | ---- | :----: | ---- | -| name | `string` | **REQUIRED**. The name of the tag. | +| name | `string` | **REQUIRED**. The name of the tag. Use this value in the `tags` array of an Operation. | +| summary | `string` | A short summary of the tag, used for display purposes. | | description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this tag. | +| 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. | +| 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