Tighten extension model

[dret]

It seems that Arazzo's extension model is a copy of OpenAPI:

• https://spec.openapis.org/arazzo/latest.html#specification-extensions

It always seemed like OpenAPI's extension model should be tightened, and maybe at least for Arazzo we can still do it? Here are two things that I think should go into almost every extension model that tries to be both open and safe:

• Extensions must always be safe to ignore, i.e. when interpreting or processing a description using an extension then it has to be safe to ignore the extension.
• Extensions are not allow to alter the semantics for anything other than their own scope, i.e. they cannot change any semantics of the base specification and they also cannot change the semantics of other extensions.

In the end, I would argue that we're simply applying the principles of good API design to our own spec.

[vanto]

If extensions are intended to extend the operational semantics, this may not be enough. In this case, it may be necessary to declare extensions at the beginning and express ignorability with a mustUnderstand flag or similar.

[dret]

On 2024-06-10 14:14, Tammo van Lessen wrote:

If extensions are intended to extend the operational semantics, this may not be enough. In this case, it may be necessary to declare extensions at the beginning and express ignorability with a mustUnderstand flag or similar.

mustUnderstand is a problematic choice for any standard that aims to be open. it's what single-handedly turned WSDL into the non-interoperable mess that it ended up becoming. as you maybe can guess, i would be strongly against such a design choice.

[frankkilcommins]

@dret - Generally, I am in favour of adding such statements/guidance for extension authors. We also should determine if we need structural changes to the extension registry to indicate what specification an extension is applicable for.

[dret]

Another (but maybe too ambitious) aspect to discuss could be the naming convention which has fallen out of favor in various specs:

https://datatracker.ietf.org/doc/html/rfc6648

[dret]

On 2024-06-11 11:49, Frank Kilcommins wrote:

@dret https://github.com/dret - Generally, I am in favour of adding such statements/guidance for extension authors. We also should determine if we need structural changes to the extension registry https://spec.openapis.org/registry/extension/index.html to indicate what specification an extension is applicable for.

oh i missed that one. it seems problematic to use the same registry for two different specs. given where OAI is headed it may be a good idea to make the registry concept more open anyways. for now what's there all seems to be "OpenAPI registries", right? we could simply add an "Arazzo registries" section, right?

[handrews]

@dret some registries might be spec-specific, but others definitely are not. The format registry, for example, isn't even OAI-specific, much less OAS-specific. If the media type modeling registry I've proposed is accepted, that's not spec-specific either. It's already true that extension keywords are not just spec-specific but also Object-specific. The best thing is probably to just add a column scoping the entries.

make the registry concept more open anyways

What would this mean? All you need to do to add to then is open a PR, that seems pretty open to me.

[dret]

What would this mean? All you need to do to add to then is open a PR, that seems pretty open to me.

For now maybe rename "Extensions" to be more specifically about "OpenAPI Extensions", and then add an "Arazzo Extensions" registry.

The other idea was that similar to IANA there could be different "sections", for example grouping all registries that apply to a specific spec. but maybe that's not (yet) needed and a bit of over-engineering.

[dret]

And I am only now realizing that the current registry seems to be less an OAI registry and more an OpenAPI registry (because registry issues/PRs go directly to the OpenAPI spec and not some separate registry repo). That's probably not ideal, assuming that other specs may follow Arazzo and hopefully we become a fertile ground for new and successful specs in the API space.

[handrews]

@dret

more an OpenAPI registry (because registry issues/PRs go directly to the OpenAPI spec and not some separate registry repo)

We're already working on that! spec.openapis.org is run off of the gh-pages in that repo because GitHub used to require that. First we are moving it to a directory on main in the same repo, then we are 99% likely to make it its own repo specifically to make it symmetric for all specifications. @frankkilcommins is involved in that discussion.

But the idea is that spec.openapis.org is where all OpenAPI Initiative projects publish their specifications and registries. The registries are emphatically not intended to be OAS-specific. They just look like that because we don't have enough people with enough time to have done all the things we plan to do (although @Bellangelo is doing an amazing job with this work and has made tons of progress in the last few weeks - he's got the PR for moving out of the special branch open right now, and that will be a huge step for us).

[dret]

On 2024-06-11 19:09, Henry Andrews wrote:

We're already working on that! spec.openapis.org is run off of the |gh-pages| in that repo because GitHub used to require that. First we are moving it to a directory on |main| in the same repo, then we are 99% likely to make it its own repo specifically to make it symmetric for all specifications. @frankkilcommins https://github.com/frankkilcommins is involved in that discussion.

that's great to hear, thanks for the great initiative and work!

[handrews]

@dret in today's TDC call we agreed to make it a separate repository. Exactly when and how that happens is still up in the air and depends on what @Bellangelo thinks will be easiest.

[dret]

On 2024-06-13 23:41, Henry Andrews wrote:

@dret https://github.com/dret in today's TDC call we agreed to make it a separate repository. Exactly when and how that happens is still up in the air and depends on what @Bellangelo https://github.com/Bellangelo thinks will be easiest.

Perfect, i think that's a good way to go.