3.3+ planning ideas

[handrews]

This collects a set of themes and areas of work I am proposing as a focus for the 3.x line in the near-ish term. Other people are strongly encouraged to propose additional areas of work! (in their own GitHub discussions). This is my personal set of suggested starting points.

I will be expanding on all of these in separate new or existing discussions/issues. Please don't get too deep in the weeds on this discussion — such comments will be moved to the appropriate feature issue/discussion if that happens.

In some cases I've linked to issues, but I have not tried to exactly match all themes to all issues. And sometimes I link to another issue with a larger list.

Organizing releases

I am not specifying what ought to go into 3.3 vs 3.4 vs whatever, as I would prefer someone else with TSC authority guide that debate and make those decisions.

The first/next/later steps organization is to help provide options for release content and scheduling decisions. It is not necessary to work all first steps first, etc.

Themes

I've grouped the work into four major themes, which are all related in some way:

• The OpenAPI Initiative is an ecosystem of three specifications
• The OAS needs to fully model HTTP interactions for both client and server
• The OAS needs to support modern security configurations and workflows
• The OpenAPI Initiative needs to understand LLM/AI use cases

We want the OAS to be powerful, flexible, and modern. There are things we know we can do, and other areas where we need to learn our community's needs.

Ecosystem of three specifications

Description authors and users need to know when to use each of our specifications, and why.

First ecosystem steps

First, figure out where we are and write it down!

• Determine which requested OAS features are best handled by Overlays
• Determine which OAS features are redundant with Arazzo
• Document use cases (or deprecations) and best practices; link to the other specs

Doing this is essential to organizing our own work and consistently and usefully communicating with users. And not just the ones that ask questions on GitHub.

Next ecosystem steps

Next, enable / encourage implementations to work together.

• Determine what is needed from the other specs to avoid feature gaps
• Allow OADs to indicate they are unusable without first applying overlay(s) (OAS and Overlays integration ideas #5120)
• Allow OADs to indicate that they should be used via Arazzo workflows

The latter two points require understanding the use cases, both for whether they should be done at all (Arazzo probably, Overlays maybe) and how (tight vs loose coupling).

Fully modeling HTTP interactions

The OAS has both low-level HTTP modeling and high-level abstracted features. Both have gaps in them, and for low-level HTTP modeling, those gaps prevent working around gaps in higher-level features. All gaps disrupt the experience of using an OAD to automate API usage (for humans or LLMs).

First HTTP steps

Header modeling is our biggest gap in describing HTTP usage. Many high-level features could be adequately, if not elegantly, supported by proper header modeling. Both @karenetheridge and @jeremyfiel have expressed interest in this, and @mikekistler brought up the Example Object naming convention.

• Create a header modeling registry analogous to the media types registry
• Clarify path matching behavior and allow manual order of precedence
• Clarify content map key media type matching with structured suffixes and parameters
• Codify correlating Example Objects based on the name throughout an operation

Note that RFC9110 §12.5.1 provides examples of matching media types with parameters in Accept.

Path matching: #213, #1970, #2015, #2356, #2530, #2564, #3162, OAI/sig-moonwalk#105, OAI/sig-moonwalk#119
Media type matching: #3162
For a (quite long) list of header modeling-related issues, see OAI/sig-moonwalk#108

Next HTTP steps

• Model media type parameters in Accept and Content-Type with minimal impact on media type matching
• Consider how to have a whole-operation example (application/http?)
• Consider WHATWG URL Patterns to enhance server-side matching

#2342, OAI/sig-moonwalk#127, OAI/sig-moonwalk#183

Later HTTP steps

• Expand matching to more of the operation (moving towards "signatures")
• Consider how to define and correlated some sort of sub-operation to address RPC and other use cases (needs to be discussed with Arazzo)

Modern Security

This area is complex and requires research and gathering expert input.

There are several great proposals including ones from @whitlockjc, @SensibleWood , and @alex-feel, but it will take us a while to understand how to incorporate all of those ideas without stepping on each other. So...

First security steps

These steps leverage existing supported behavior to allow workarounds for current limitations, and to allow Arazzo to define auth workflows where we are unable to describe them with Security Schemes.

• Add application/jwt and other security/encryption-related media types to our registry
• Allow defining authorization / token / etc. servers in addition to API servers
• Allow modeling auth endpoints like API endpoints

An alternative to the last two would be modeling auth servers with their own OADs and using Arazzo to connect them, but as some auth behavior is a bit different, that might actually be harder. But worth considering.

Many of the following issues could also get more elegant solutions in next/later steps, and for a few it's not clear where they fit: #61, #1416, #1464, #1731, #1881, #1995, #2027, #2232, #2284, #2296, #2322, #2419, #3983, #4836, #4925, OAI/sig-moonwalk#84, OAI/sig-moonwalk#50

Assuming full header modeling support and Overlay support for adding configuration to every selected endpoint, more-or-less every requested security feature could be modeled this way. Although not elegantly.

Next security steps

We probably want to be starting these alongside the first steps, I just think they'll take longer.

• Enhance Security Schemes to support more configurations elegantly
• Collaborate with Arazzo on security integration, which is already happening

Some bits of these issues go here, some in the "Later security steps": #1702, #1875, #1934, #2239, #2398, #3612, #3709, #4106, #4807, OAI/sig-moonwalk#46, OAI/sig-moonwalk#69

Later security steps

• Rethink our whole approach to separate concerns and provide a comprehensive and extensible framework, with clear divisions between the OAS and Arazzo

Understanding AI use cases

For this, we need to convene a SIG, do a lot of research, and talk to a lot of people.

However, we know that gaps in HTTP modeling and security support make it harder for LLMs to consume an API, so the above proposals have been chosen in part with that in mind.

[handrews]

[EDIT: See #5120 for this whole response thread split into its own discussion- the hidden comments have been moved there.]

BTW I don't want to get into a deep debate of these options, I just wanted to note the range of possible solutions that I had already considered. We should debate the specifics elsewhere if we decide to prioritize this.

[lornajane]

This might belong somewhere else but I'd also like us to consider working as a group on activities beyond specification writing. What do the users of the specification need from us to make it more useful or usable? In particular, can we support wider adoption or upgrades in some way?

[handrews]

@lornajane I think this is great to bring up here as that sort of work would inform our prioritization and selection of work areas.

[handrews]

@lornajane I always come back to "we should make sure the Learn site is comprehensive and up-to-date." Or at least up-to-date. We've debated what goes on Learn vs in the spec several times, and I think that would be an easier conversation to have if the Learn site was more consistent and current.

I'm not the best person to actually write the updates, but I could audit the current pages for correctness and note which ones are stylistically divergent. It would be good to have a style guide for Learn writing (paging @SensibleWood ) so that more people could contribute while keeping a cohesive feel. For example, the pages I added on referencing could be rewritten both to have a better focus and to align with the style of pages like the Security page.

Although perhaps we might also want to consider why so many vendors have their own help pages, and how much we want to be in competition with those.

[handrews]

@mikekistler @SensibleWood @baywet I've started discussion #5120 for the OAS/Overlays integration. have copied all of your comments over there and hidden them here to re-focus this discussion on the meta-topic of release planning.