Minimum criteria for Namespace Registry

[miqui]

Background:

During the TDC Meeting on 2/15/2024, I raised the point of contributing to the namespace registry. In particular, I wanted to add the extension for AWS x-amazon-. This also raised the question of the minimum criteria for the extension to facilitate the proper PR contribution triage.

Proposal

To determine the minimum criteria that would assist the PR approver in determining if the extension belongs in the OpenAPI Initiative Registry. There is a process to create a PR or an issue to trigger a discussion.

Doing some research, this blog entry by the Postman Open Technologies team mentions the notion of extension profiles. This entry describes the potential problem whereby anyone can add an extension to their OAD. However, I believe we want to limit the extensions that SHOULD be in the OpenAPI namespace registry for the broader community understanding and/or use. An excerpt from the blog entry:

It addition to above, it might be desirable to:

• Be able to differentiate between extensions from major organizations (industry vendors, government agencies, international >organizations, standard setting initiatives) vs more confined extensions (from projects, individuals, students, R&D).
• Understand which disciplines or domains an extension is intended for
• Have mechanisms for capturing usage / popularity and support user feedback

I think that for now, we should:

• Focus on extensions from major organizations
• The organization in question MUST have a URL documenting their extension

Please note that the format proposed by the OAI is x-{namespace}- where {namespace} is a unique string associated with the creator of the extension within the namespace and it MUST be registered lowercase. However, some organizations like GitHub while they do have x-github- they also have extensions that do not meet either of these criteria. In such a case, I would say we just stick to the x-github- extension and, in the description include a URL where someone can explore their other extensions.

Note:
Mike Ralphson has a rather comprehensive list of extensions found in the wild.

[miqui]

cc @darrelmiller

[lornajane]

Do Amazon use a standard prefix for extensions? I've seen x-amzn-* in other places.

I was not present in the community when the conversations around "extensions" vs "vendor extensions" took place, but I think that would be relevant to have a brief recap from someone who might have that context (or can point to something we wrote down at the time).

[miqui]

@lornajane - it is on the agenda for this week, I can recap. I have not seen this one, x-amzn-*, but it should not be considered if it is not officially documented. The official AWS docs do not mention x-amzn-*. (at least I could not find it.)

Thanks for your feedback!

[earth2marsh]

I was not present in the community when the conversations around "extensions" vs "vendor extensions" took place, but I think that would be relevant to have a brief recap from someone who might have that context (or can point to something we wrote down at the time).

For 2.0 we introduced "vendor extensions" as a way for tooling to represent implementation details in a spec. Only later did we realize that framing it specifically as being for vendors was too narrow, so we relaxed the name to just "extensions."