What are the requirements for managing context in specifications?

[frankkilcommins]

The general thinking process around the formation of this SIG, is that we want to be able to define additional context which convey the goals, or key functions, of an API (possibly even a group of APIs).

Examples

• The Petstore API has an example goal of purchasing a pet
• The Auth API has an example goal of obtaining a refresh token

In this discussion thread, we should aim to discuss valid use-cases and/or requirements for defining and managing the context representation. This can lead us to taking an initial pass as it's inclusion in the SIG proposal document.

Primary discussion points:

• Discuss standard for defining the key context (possible extensions to OAS, alternative specifications, etc.) with the aim of avoiding alphabetical listing of all spec items and exceed what is possible by tagging and verbose text and/or examples prose.
• Discuss wordings/terminology (e.g. recipe, goal, step, flow, workflow) - strive to avoid existing nomenclature

[ankrim]

I’m trying to categorize the different use cases to maybe help us clarify some of the details and the scope of workflows that we can or should support in this spec.
There are probably many ways to define these categories but I feel like one of the main categories is the number of “participants” in the workflow.

This comment talks about one of the OpenID Connect flows - #10 (comment) and as you can see it only works with multiple participants.
On the other hand the “purchasing a pet” workflow is for a single participant.
Another example for a use case that has multiple participants is an approval flow.

I wonder if another dimension for this categorization can be single or multiple APIs, but it’s probably not as important and most of the spec should be the same in both cases.
As an example - the “purchasing a pet” workflow uses a single API (the petstore), but maybe the travel use case that was mentioned before uses multiple APIs (maybe book a flight, book an hotel room and a car rental APIs from different vendors).

I’m mostly thinking about this from a code generation perspective - how can we use the spec to generate a client to execute the flow, and in this case the flows with multiple participants are probably the most complicated. Maybe from documentation and other perspectives it’s simpler.