Additional fields for the tag object #4288
Conversation
|
Love this. As an implementor, the first thing that comes to mind is "now I need to write an interface "get me a list of all the operations with a particular tag kind". |
|
Co-authored-by: Mike Kistler <[email protected]>
| | <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. | |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
but if the tag is defined and has a parent, then I think that parent should be defined too.
+1
There was a problem hiding this comment.
@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.
Implementation of the proposal to extend the functionality offered by tags. The main features:
summaryfield in addition to their descriptionkindto say what sort of tag they are, so we can use tags for many; Add tag kinds registry to the spec site #4287 adds a registry for the most common typesPull request still in draft because I would like to link to the registry but it doesn't exist yet so we should not merge - review feedback very welcome though!