OpenAPI Initiative specifications: Scope / vision statements

[handrews]

• The OpenAPI [Serialization] Specification describes how to serialize application data structures to HTTP messages, and deserialize HTTP messages to application data structures
  • This is much more concise than the current introductory paragraph of the OAS, although perhaps less end-user friendly? Maybe there are different audiences- spec readers vs potential spec contributors?
• The Overlay Specification transforms (valid? usable? ???) OpenAPI Description documents to (valid? usable? ???) OpenAPI Description documents, using documents that are separate from the input and output OADs
  • This attempts to incorporate conditions on input and output into what the Overlay Specification's intro paragraph already says. I don't think my proposed wording here is great, it's just a starting point for discussion
• The Arazzo Specification provides a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions).
  • This is just a copy-paste of Arazzo's intro paragraph. It could maybe be a bit more punch-y if we want to put these statements together on a web page, but that's a minor quibble.

In the context of Moonwalk, we could have a fourth specification:

• The OpenAPI Semantics Specification adds semantic information, for humans and/or LLMs, to an existing (valid? usable? ???) OpenAPI Description, at an individual operation granularity
  • _This is not the greatest wording, but again, a starting point. The "individual operation" granularity is an attempt to explain the boundary with Arazzo. Or perhaps motivate a discussion about whether things should instead go into Arazzo.

---

In addition to these high-level statements, which are what I'm mainly focused on, there are practical overlap concerns that need to be hammered out. These should be done on an as-needed basis, rather than spending a lot of time trying to draw pre-emptive boundaries that might hinder innovation. Some known ones, or topics that might end up relevant to scope:

• Arazzo and the OAS Link Object (and other overlaps and integrations) Arazzo-Specification#380
• Arazzo and the OAS Callbacks Object Arazzo-Specification#398
• Support semantic OpenAPI expressions for targets Overlay-Specification#128 (if we separate API serialization and semantics, semantic selection becomes an interesting boundary problem)
• Are there plans to add support for global responses? #5006 (pretty much the classic OAS vs Overlay scope question)
• OAS and Overlays integration ideas #5120 (stumbled into the question of what sorts of OADs are in-scope for the Overlay specification)
• OpenAPI 3.3 Proposal: API-Level Deprecation & Sunset Support #5193 (proposal with both serialization and semantic aspects, where the serialization could probably be done with the existing OAS, or with OAS + Overlay)
• Support specifying log levels for the attributes in an OpenAPI spec #5174 (arguably primarily application semantics, not serialization)
• Proposal for OpenAPI Extension: x-sensitive-data #4330 (similar to the previous)
• Investigate OpenID AuthZEN #5172 (interesting question as to whether authorization (as opposed to authentication) is more semantic or serialization-oriented, or how to best arrange semantic vs syntactic parts)
• Semantic tagging for interoperability (of 3rd party cloud platforms) #4651 (directly about semantics)