New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create specification extension registry #1351

Open
darrelmiller opened this Issue Sep 16, 2017 · 7 comments

Comments

Projects
None yet
5 participants
@darrelmiller
Copy link
Member

darrelmiller commented Sep 16, 2017

No description provided.

@dret

This comment has been minimized.

Copy link
Contributor

dret commented Sep 16, 2017

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

This comment has been minimized.

Copy link
Member

MikeRalphson commented Sep 18, 2017

@tedepstein

This comment has been minimized.

Copy link
Contributor

tedepstein commented Sep 29, 2017

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

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

@MikeRalphson

This comment has been minimized.

Copy link
Member

MikeRalphson commented Sep 30, 2017

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

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

@tedepstein

This comment has been minimized.

Copy link
Contributor

tedepstein commented Oct 1, 2017

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

This comment has been minimized.

Copy link
Contributor

dret commented Oct 1, 2017

@tedepstein

This comment has been minimized.

Copy link
Contributor

tedepstein commented Oct 1, 2017

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment