Proposal: Add externalLinks, like externalDocs but allow more than one

[lornajane]

This proposal is a suggested approach for addressing this long-standing issue #1034 where quite a lot of people have asked for the ability to add more than one resource at a time.

AI disclosure: talked through with Claude and got the sillier ideas out of the way before proposing this approach, but the writing is my own.

• no schema changes are needed for this pull request

[akrabat]

As the External Documentation object is being extended with summary here, is it worth adding tags too?

I can imagine having more than one type of link in the list and it may be handy to be able to classify or filter them based on tag.

[lornajane]

From TDC meeting: agreed to update the draft to add a kind field to classify link types

[lornajane]

Proposal amended to add a kind field to give support for describing what type of resource is linked. The kind naming is aligned with the same "grouping" type of pattern that was used in the tags from OpenAPI 3.2 onwards.

[miqui]

@lornajane

My 2 cents:
Today's externalDocs gives you one URL with no signal about what kind of thing it points to. An agent has to fetch it, read it, and infer relevance — expensive and unreliable at scale.
externalLinks + the kind field (auth, api-docs, changelog, etc., pulled from a shared registry) turns that into a lookup table. An agent can ask "does this operation have a kind: auth link?" without fetching anything, and only pull the resource that's actually relevant to the current task.

Very important on being optimal fetching + inference

one caveat:

kind is a free string, not an enum. The registry gives you recommended values, but nothing stops an author from writing kind: docz or leaving it off entirely. An agent's filtering logic needs a fallback (read summary/description with light NLP) for non-standard or missing values.

[baywet]

could / should we have a default value for kind? and maybe a reserved "documentation" kind? To functionally map with externalDocs.

I'm especially thinking about people upgrading to 3.3, who already have an externalDocs, and would want to get out of using deprecated fields. Having a reserved key that maps functionally, and maybe a default could make that upgrade path more straight forward.

Note: I'm not suggesting we can only have both a default and a reserved key, but we should consider each or potentially both.