Arazzo and the OAS Callbacks Object

[handrews]

In discussion #380, @frankkilcommins said (in reply to one of my comments):

What about Callbacks? That is another workflow-ish thing in the OAS, but definitely a bit different (I can open a separate discussion if preferred, but I'm kind of making this a general OAS/Arazzo overlap discussion at the moment).

I would prefer a separate discussion/issue on that topic. Part of the proposal for AsyncAPI will be adding features that make leveraging callbacks and/or webhooks as part of a workflow more manageable.

So here is a discussion for Arazzo and callbacks. And maybe webhooks. It's not entirely clear to me how they fit, and whether they should be in the same discussion, although I suppose a webhook call could start a workflow? [EDIT: we'll just focus on callbacks in this discussion]

For OAS 3.3 work, the main questions are:

• whether we want to deprecate anything in favor of Arazzo (probably not for callbacks yet, as the related AsyncAPI integration is still in progress)
• whether there are opportunities to link from OAS to Arazzo by saying things like "if you have use case X, please see the latest Arazzo Specification."

As I noted in OAI/OpenAPI-Specification#5116, we want to leverage the popularity of the OAS to raise awareness of Arazzo and Overlays. And we also want people using two or all three of our specifications to feel like there is a coherent experience to it all.

[kevinduffey]

So I assume OAS 3.3 will be a ways out (e.g. several months) before a draft is put out for feedback? I believe the hope is to have Async integrated into the Arazzo spec by end of year (that is the hope) for review so unless I am misunderstanding the speed with which the next OAS 3.3 is going to be somewhat ready for review I would assume Async will be in Arazzo before then. With that in mind, I would say if there is ever going to be a time to deprecate webhooks (and links) given the typical duration of a .y spec for OAS, now might be a good time to put that out if the OAS group agrees. It will still be in OAS 3.3 if I understand the nomenclature around deprecation.. it's like a hint that by 3.4 or 3.5 it will no longer be part of the spec, but for now it's still there, just start moving away from it. Yah?

I don't personally see why we would link to an Arazzo description from an OAS description with the one possible exception of "Hey.. this operation is used by THIS here arazzo description". BUT.. any tooling that loads arazzo descriptions will see the source descriptions, import the OAS descriptions and make those connections I would assume. Since many Arazzo descriptions could import the same OAS description, having a link in one saying "Yay.. I am used by this Arazzo description" wont be of much value to other Arazzo descriptions using the same OAS description. I almost feel like if we did have some sort of link like that, it might start another "my OAS is out of sync because 4 other Arazzo's now use it.. and I did not know that" war.

There would be nothing stopping an x- extension being added by a tool or OAS author from adding it in that way and to your point, if the OAS and Arazzo descriptions are internal to one company, there certainly is no harm in the author of the OAS from adding that info if they want, but I don't think we'd want to put this as some sort of property or feature in OAS or Arazzo, especially given the extension mechanism that already exists for such capabilities.

Just my .02.

[handrews]

@kevinduffey

So I assume OAS 3.3 will be a ways out (e.g. several months) before a draft is put out for feedback?

We haven't even scoped OAS 3.3 yet much less set an aspirational date. I personally would like to release 3.3 by the end of 2026, but the emphasis there is personally. This discussion and #380 are part of the exploratory scoping work.

It will still be in OAS 3.3 if I understand the nomenclature around deprecation.. it's like a hint that by 3.4 or 3.5 it will no longer be part of the spec, but for now it's still there, just start moving away from it. Yah?

Deprecated features will still be present throughout 3.x, and removed in 4.0. This assumes we don't do too many more 3.x releases before deciding we know enough to do a breaking syntax clean-up and call it 4.0. If that changes, we might adjust the policy, but that's what it is right now.

The point of deprecating an OAS feature is to communicate:

1. We're not going to enhance this feature further.
2. In place of the deprecated feature, we formally reference Arazzo or Overlays as the replacement

There are some corallaries here. If an implementation has never supported a deprecated feature and no one is asking for it, it's pretty safe to just not do it 😛 And if we're going to point to Arazzo and/or Overlays, those specifications need to be clear on the replacement use cases.

Anyway, if AsyncAPI support is going into a relatively immanent Arazzo release, then yes, 3.3 would be the ideal time to address this. There is a lot of enthusiasm for 3.3 making it clear that the OAI is a multi-specification ecosystem, and presenting things accordingly.

[kevinduffey]

Well.. unless something happens that drags it on.. and that could happen.. the goal is soon to have it at least in preview mode so we can get eyes on it from lots of people to ensure it makes sense, should work with tooling support, and so on. Unless I am mistaken this would make Arazzo the first spec that cleanly integrates sync and async "steps" in to workflows. I think it will greatly enhance the capabilities of workflows that currently in my experience requires whiteboard team sessions and someone coding things up to see how it works. So I am hopeful this is going to open the doors to some exciting new ways to design and implement software especially in the age of AI.

[frankkilcommins]

@handrews let's scope this discussion to just callbacks. I've updated the title accordingly.