Create specification extension registry

[darrelmiller]

[dret]

it is very interesting to see this. https://tools.ietf.org/html/draft-wilde-registries-01 is where i have started writing up considerations that go into why having registries, what to put into registries, and how to manage them. it's a fascinating topic and IANA's ~2000 registries demonstrate that it's an important pattern for open information architectures.
so it definitely is exciting to see this on the roadmap. i have been playing with the idea of building a registry around git(hub), so that the registry is managed via git, can be published via jekyll/pages, and can use github features such as branches and issues and access management to support the desired registry management workflow.
if that's something that seems interesting for the OpenAPI extension(s) registry, that's something where i'd volunteer to get something off the ground to have a well-designed and -managed extension registry.

[MikeRalphson]

Summary of existing extensions seen in the wild: https://github.com/Mermade/openapi-specification-extensions/blob/master/extensions/combined.tsv

[tedepstein]

@whitlockjc , @darrelmiller , some possible contributions to the initial registry from @kinlane:

http://openapi.toolbox.apievangelist.com/extensions/

[MikeRalphson]

Additional links to (OpenAPI 2.0 usage of) various specification extensions, by vendor:

https://github.com/Mermade/openapi-specification-extensions#vendor-documented-extensions

[tedepstein]

Related to this discussion, I asked on Friday's TDC call if there's any standard or proposed standard for a machine-readable description of specification extensions.

Today's OpenAPI editors tolerate these extensions, but don't usually provide specialized code assist, tool tips, or validation for them. Specification extensions are kind of a second-class feature of the language, where most editors are concerned, unless we go to the trouble of supporting specific extensions that we think are important, in a completely proprietary way.

The answer came back that there is no such standard, as far as we know. So I took some time this weekend to draft one:

https://github.com/RepreZen/Semoasa

Please comment!

(To clarify, a machine-readable metadata standard is not a registry, nor a pre-requisite to creating a useful registry. It's also not in scope as a feature of the OpenAPI specification itself. But I'm posting the link here because it's related, and hopefully of interest to you if you're following this issue. )

[dret]

On 2017-10-01 19:37, Ted Epstein wrote: Today's OpenAPI editors /tolerate/ these extensions, but don't usually provide specific code assist, tool tips, or validation for them. Specification extensions are kind of a second-class feature of the language, where most editors are concerned, unless we go to the trouble of supporting specific extensions that we think are important, in a completely proprietary way.

not having an elaborate extension description model does not turn them into "second-class" in a negative sense, but of course they are not part of the spec itself. not having *extension discovery* is a different matter, and in my mind is the more important first step: https://tools.ietf.org/html/draft-wilde-registries afaict, there are far more open standards where the discovery/registry model proved helpful and successful, than there are open standards where a universal description model had the same success. the usual problem is that extensions have different motivations, and it's hard to predict these. but: i think that machine-readable registries alone would be a step forward, so that at least there is some possible automation that can be built around how to handle unknown extensions. but what to *expect* when then looking at them, that is an entirely different matter.

(To clarify, a machine-readable metadata standard is not a registry, nor a pre-requisite to creating a useful registry. It's also not in scope as a feature of the OpenAPI specification itself. But I'm posting the link here because it's related, and hopefully of interest to you if you're following this issue. )

to me, such a standard could be one that extensions use when you started to explore them. but the first question always will be: how to you even find a place where to go, when encountering an extension?

[tedepstein]

@dret ,

"Elaborate?" Really? It's basically a name, a JSON schema, and a list of objects where the extension can be used.

To be clear, I'm not trying to position Semoasa as a replacement for the human-readable extension registry proposed in this issue. Not proposing anything that would impede the goal of extension discovery. And not proposing to expand the scope of this current issue to require, or even include, optionally, a link to a machine-readable description. That could always be added later, as and when the community finds it beneficial to do so.

Since what I'm proposing is separate from the OAS extension registry, I've opened a new issue here in the Semoasa repo to continue this discussion, and I'd invite others to comment there or open new issues.