Add guidance on externally documented extensions via extension namespace doc

[DavidBiesack]

See #106

@handrews wrote:

I think we need:

The main Registries page to explain this (easiest option would be in its own paragraph beneath the current one)
The Extension Field Registry / Extensions Registry (we should make the heading on the page match the heading in the list on the Registries
page while we're at it) should link to the namespace registry, noting that more extensions can be found there
A "Repository" or "3rd-Party Registry" or something column in the Namespace Registry table between the "Prefix" and "Description" columns
Updated guidance in the spec repo's CONTRIBUTING documentation

This issue is to update the registries doc on openapis.org to provide better guidance on documenting extensions via external documentation that a provider may link to from the namespace registry (similar to how the x-mx namespace links to documentation on the extensions they use, rather than listing each extension in the extensions registry.

I also suggest OAI provide a recommendation for such external extension docs or a format (JSON Schema) for such content, so such external documentation is more uniform and machine readable. (I thought there was a proposal for something like this a few years ago, but I can't find it.)
The Markdown "template" used in registries/_extension/*.md is partly there, and relies on structured Markdown frontmatter, but it is still a bit too irregular (i.e. "Used by" is in plain text in the body, not structured data)

[baywet]

Thanks for opening this up.

@mikekistler and I discussion on the topic, and I think further discussions from the TDC are required to make decisions before we can make updates here and provide clear guidance. I'll try to recap the point of views here.

namespace and external registries

Essentially, what I'm proposing/thought was already the current practice when I reviewed your initial PR was the following "bucketization" of extensions:

• Vendor specific extensions: those live under a namespace e.g. x-ms-enum, should be defined on an external registry, and are meant for internal use all the way to "interoperability between multiple vendors".
• "open extensions": those are not namespaced, live on the current registry, enable better interoperability, require a review. Eventually they might "graduate" into a specification feature, or a SAF.
• OpenAPI reserved extensions: those are namespaced (x-oai/x-oas/x-jsonschema), reserved for things like graceful downgrades from one version of OpenAPI to an earlier version etc.

The benefits being:

• reduced maintenance burden on the maintainers from reviews
• keeps the current registry focused and easier to parse/read/manage
• reduced latency for namespaced extensions.

namespace and shared registry

While @mikekistler was not opposed to external registries use, he suggested we should not make "any namespaced extension should live on an external registry". The benefits of doing that are:

• they are easier to discover
• lower setup cost
• the reviewers can inform the design, benefiting the vendors
• informs the TDC about "what's needed" through passive exposure during the reviews

[handrews]

@baywet I think I'm with @mikekistler here, or at least share his concerns. We are not exactly flooded with extension registry PRs right now, and our lack of awareness of what is out there is a problem. At the same time, I don't want to require vendors with large extension libraries to go through a complex process.

Perhaps we should merge the namespace and individual extension pages and include a link through to any external registries? My main fear with only using external registries is that people won't look at the namespace registry page as much, and not think to click through. But if we merged them, then making which ones are namespaces and lead to more extensions clear on a single page might be a good way to split the difference?

[handrews]

BTW I think doing that (merging pages) would also allow folks with namespaces who don't want to maintain an external registry to register both their namespaces and individual extension clearly.

[baywet]

In this merged pages version, if a vendor wants to maintain an external registry, they'd have a single entry pointing to it.
If a vendor doesn't want an external registry, what would they have? the individual extensions? that + a namespace registration?

Also, do you happen to remember why namespacing was introduced in the first place? neither of us could remember.

[baywet]

Here are the commit and the associated issue for reference
2c2162e

OAI/OpenAPI-Specification#3107

[handrews]

If a vendor doesn't want an external registry, what would they have? the individual extensions? that + a namespace registration?

Presumably? I suppose they could just register individual extensions and let the namespace be implied, but I'd rather see a namespace row indicating that the namespaced extensions are in this registry.

I think we have a namespace registry because someone suggested it. I do remember it being discussed but I don't remember what was said. I think it was not controversial enough to be memorable :-)

[baywet]

We discussed about that today during the TDC call. Here is the conclusion we came to:

• namespaces extensions might live on an external registry maintained by the vendor, or here. We're ok with both approaches
• we'll try to regroup the namespace and the extensions pages, so all extensions are easier to discover
• should we get too many extensions, in particular namespaced ones, we'll reevaluate/organize the content as needed.

I'll go ahead and prepare a PR for the guidance. @handrews has offered to put together a PR for the regrouping of the pages.

[handrews]

@baywet I'm going to re-open this because I had forgotten there were still things for me to do here.