Define the need for documentation beyond the current scope of the OAS

[swaldron58]

On the premise there are solutions to challenges such as how to communicate workflow, data security (PII), user security (identity management) and other complicated scenarios that are difficult or impossible to address in the OAS, the issue is to recommend a sustainable approach to OAI providing additional documentation. Basic decisions need to be made such as if any additional types of documentation define by OAI are to be machine readable in format, human readable, or both are allowed. The initial work is expected to be the creation of use cases to provide context and better understanding of the need. These use cases need not to be held to a criteria that they can’t be solved by additions to the OAS, just that they may be solved in a more useful or consumable way outside of the OAS. The scope of this issue is to list and agree on a set of actions and constraints to move forward.

[swaldron58]

Draft statement of the issue:
The OAS currently focuses on discrete API operations with no implications of what happens before or after this instance of an API call. There are scenarios where there are specific or implied relationships between a group of APIs that can not be expressed in a machine readable format in the OAS and hence can only be communicated out of band by some other means. The draft proposal is to create a machine readable format that would be useful to tool providers, now or in the future, that provides actionable instructions of the intended relationships within a group of APIs. An example in travel would be a group of APIs that collectively make up a shopping, booking, payment/ticketing sequence where the machine readable documentation would express the sequence including the addition of ancillaries and upgrades along with the basic (seat/room/car/berth) product. Other examples are well documented in identity and data security protocols but still at this time left up to developers to sort out how it actually works at the API level.

[lornajane]

@swaldron58 does the Workflows specification https://github.com/OAI/sig-workflows address this issue, or would you still feel that there's action needed on the main project?

[swaldron58]

Hmmmmmmm. Sort of. Workflow as defined by the workflow sig created a separate sperate spec. As an organization, OAI could have worked out ahead of time that we would have adjunct specs and how those were to be managed including codependencies. But as it happened, we defined a separate spec but without detail on how this all will be managed. Actually either approach is fine. My point being we still have work to do around definition and documentation of the process. Set guardrails for this and future efforts. Not a big deal to do, but we should define some boundaries.
So to answer the question, workflow does establish we will have adjunct specs, but we have more work to do define how it works.

[handrews]

@swaldron58 Are you basically asking for more process and scope definition around the OAI/learn.openapis.org repository?

[swaldron58]

With workflow and to some extent overlays the discussion has been positive to do something in these areas but we found, I’ll say, less than obvious how to squeeze this into the one spec. As a group we also discussed that in the spec was pretty broad already to the point of being confusing. Hence an logical (to me) decision to have separate specs. But there are some constraints we may want to consider.
• Do we want to require or at least heavily recommend any ancillary spec is adhering to the OAS? That is, don’t break the OAS just because that makes your current work easier. Make the effort to go back to the TDC and propose a change to the OAS. Don’t just ignore the issue.
• What version control is required? If an ancillary spec is not backward compatible to older spec versions, who monitors that? If a spec change breaks an ancillary spec, how does that work? Easy answers to most of this but we should document what is expected from all teams.
• From a marketing viewpoint, do we want spec releases to coincide or just let teams publish when they are ready?

None of this earthshattering. But we should communicate some guidelines. I don’t think this is already documented somewhere and I am not clear on where that would be. So maybe in OAI/learn.openapis.org .
I don’t want to over engineer this but this may be a reason to actually have Technical Oversight Board meetings. Maybe at least once a month. The TOB is in our charter but ignored.

[handrews]

I don’t want to over engineer this but this may be a reason to actually have Technical Oversight Board meetings. Maybe at least once a month. The TOB is in our charter but ignored.

Yeah, this makes sense to me. There hasn't really been a broader techincal landscape for the TOB to oversee, but with progress on more SIGs (at least Workflows and possibly a rejuvenated Overlays) and the need to sustain 3.x while moving ahead on Moonwalk, there are suddenly a lot of moving parts. And the relationship of all of these things to less formal things like the Learn site would also fit there. We might want to re-think for Moonwalk the level of detail and volume of examples in the spec itself vs a supplemental place such as the Learn site.