What principles can we define to help identify priorities?

[earth2marsh]

With v4 we have a chance to be more specific around priorities, such as:

• When in doubt, consider the impact of changes or improvements to API consumers first, OpenAPI document authors second, and tooling authors third
• It is more important to be expansive than to have opinions OR it is more important to have opinions than to be descriptive (this is a oneOf!)

If we can agree on a handful of these, they may facilitate decisions in the future. If not, we can close and move on.

[DavidBiesack]

I see some additional principles that may be orthogonal to those @earth2marsh cited but worth considering when making decisions:

1. remove ambiguity
2. consistency/predictability (reduce/eliminate exceptions, surprises). Internally consistent (see A reference to something should always be a JSON pointer and not a name (security scheme example) #26 for example ) , and also consistent with related standards such as JSON Schema, HTTP, and so on.
3. expressiveness / flexibility and other "ease of use" principles (what kinds of APIs can and can I not describe with OpenAPI 4?)
4. extensibility - allow the specification to grow/extend over time (4.1, 4.2, 5.0)
5. Simplicity over complexity (reduce cognitive load)

[DavidBiesack]

On 3, 4 and 5: see also @darrelmiller's note in #24 :

OpenAPI itself should remain simple for simple stuff, but make the tricky stuff possible.

[earth2marsh]

Some points/topics/questions that came up during today's discussion:

• Prioritize humans over machines?
• How code-like is an OpenAPI document?
• Design vs definition, should we be splitting that?
• Describing vs modeling vs validating? We risk breaking that "one language we all speak". What is the demand for this split, can we quantify?
• Is our strength the interoperability of tools?
• Happiness vs ubiquity
• Constraint system, see https://modern-json-schema.com/json-schema-is-a-constraint-system

General agreement that it is important to continue this conversation and to describe the overall purpose of v4.

[handrews]

@DavidBiesack I'm going to copy your comment from OAI/OpenAPI-Specification#676 over here for posterity so I can close that out (the discussion definitely belongs in this repo now):

There are some high level goals for OAI/OAS:

1. The goal of the OAI specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.2

However, these goals do not necessarily map to lower level decision criteria when looking at issues/proposals/pull requests. How does OAI/TDC resolve two competing and conflicting proposals which both satisfy the above goals?

Examples of questions/proposal in need of guiding principles:

1. "If OpenAPI wants to be agnostic about design-first vs code-first, then the specification has to be able to adequately describe real world APIs. I don't think any decisions about inclusion in the specification should be determined by how easy or hard it is for a tool to implement. That is a problem that can be solved elsewhere, and if tool authors don't want to deal with it, then let them implement workarounds. By omitting something like this from the spec entirely you just force the problem on the users." Support for Either OpenAPI-Specification#57 comment.
2. To that I would add the design to capture HATEOS Allow documenting HATEOAS APIs (pathless operation / interface / URI class / operation type) OpenAPI-Specification#577 so we can wean clients from RPC style tightly coupled clients/servers
3. To what extent should OAS be constrained to JSON Schema and other syntactic notation, vs. higher level abstractions to express things like schema inheritance) Adding merge construct OpenAPI-Specification#674 comment Group multiple parameter definitions for better maintainability Overlay-Specification#34 comment

I suggested drafting a set of Guiding Principles which can be used to concretely evaluate proposals.

For some examples of Guiding Principles to consider:

1. to what degree does tooling support (Swagger UI, Swagger Editor, Swagger codegen and hundreds/thousands of other tools) impact specification decisions?
2. To what degree to we rely on the crutch/claim "tooling can improving the experience"
3. How much do we weigh the ability to capture RESTful designs (such as HATEOAS) first and foremost, vs. toolability?
4. Convention over configuration. (Does a path parameter really, really have to have a required, explicit required: true?)
5. Does a lowest common denominator (such as target language/library etc.) skew OAS design choices?
6. How highly do we value making OAS documents readable/understandable/editable by humans?
7. How extensible is OAS both through structural decisions (not just x- specification extensions) Support for multiple request/response models based on headers OpenAPI-Specification#146 is the poster child...
8. Evolvability, maintainability of specifications
9. Removing ambiguity, misinterpretation
10. Conciseness
    etc

We may not be able to get purely objective criteria, but then again, principles are usually more subjective than objective.

[handrews]

And now @timburks ' reply to the above quote from @DavidBiesack :

I think this is worth more discussion.

There's a tension between "meeting developers where they are" and making value judgements and promoting good practices. One feature of OpenAPI that will help it and the API ecosystem grow is abstraction. By allowing implementation details to be hidden by generated code or other adaptors, OpenAPI can make it easier for more people to be API developers and users. But this requires high-quality tooling, and adding complexity to the spec to include more stakeholders makes that more difficult.

There is a purpose statement on the home page of the Open API Initiative: "Open API Initiative (OAI) is focused on creating, evolving, and promoting a vendor neutral API Description Format based on the Swagger Specification." But the value of that isn't directly stated. The best justification that I could find is on the About page: "Creating an open description format for API services that is vendor neutral, portable and open is critical to accelerating the vision of a truly connected world." Based on that, "meeting developers where they are" is true to the Open API mission, but as I hinted above, I don't think that's the same as making it possible for more people to easily create and use APIs, which would include picking and promoting best practices that can be well-supported by automation and accessible to future users.

[hudlow]

@earth2marsh, thank you for raising this. I think it's a very important topic, but also an extremely challenging one.

I haven't been able to track with all the conversations happening in the OpenAPI community for the past few years, but I've been working with OpenAPI every day and (thanks to @mkistler) do have a sense of some of the bigger debates (in addition to the pain points I've experienced myself). You'll have to forgive me if some of what I say is obvious or settled — I'll try to catch up.

I suspect we'll have a lot of trouble coming up with a comprehensive set of personas and a simple conflict resolution litmus test. And — maybe it goes without saying — I think we'll always need wise and empathetic leadership to balance conflicting needs.

But just because we can't make decisions automatically doesn't mean we can't start closing the gap between the high-level values described for OpenAPI and the way concrete decisions about 4.0 are made. I think doing so is important in order to make decisions more consistent, give us a shared compass, and frame debates as good-faith efforts to achieve shared objectives.

Existing values

A few things stand out as a starting point for this in the OAI charter. First, in the mission statement:

The OpenAPI Initiative (“OAI”) provides an open source community, within which industry participants may easily contribute to building vendor-neutral, portable and open specifications for providing technical metadata for APIs [...]

And then in a few of the core values:

b. Collaborative: interested parties shall have the means to freely contribute ideas, solutions, commentary and other input to the evolution of the Specifications.

d. Pragmatic. The Specifications should prioritize to solve real world problems over supporting academic / abstract concepts.

e. Extendable. The Specifications should allow domain-specific extensions to adhering definitions – enabling the use of the Specifications without having to be in conflict with their core functionality.

Finally, OpenAPI itself says:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

Objective

I propose that the overall goal should be to make as many API stakeholders as possible able and content to use OpenAPI, even if that means OpenAPI is not fit for use or ideal for the maximum number of users possible.

I enjoyed an analytical framework @jgeewax describes in his book, API Design Patterns, for a similarly over-constrained problem: API versioning and compatibility. JJ looks at how a few different approaches balance a tradeoff he terms "happiness vs. ubiquity."

This tradeoff, JJ explains, is about how the decisions you make distribute your users into four camps:

• Cannot use
• Mad
• Okay
• Happy

I think this is a useful way to frame tradeoffs for engineering decisions — in general — that have a lot of stakeholders. JJ explains if you try to optimize for the maximum number of happy users (for OpenAPI, this might be on the extreme end of "more opinionated but less expressive"), you'll end up with a large cannot use camp.

Whereas if you try to eliminate cannot use (perhaps on the extreme end of "more expressive and less opinionated"), you'll probably end up with a dominant mad camp.

One might use these last two examples, respectively, as a perspective on why ideologically pure REST/HATEOAS (interesting and exciting, but unsuitable for many use cases) and SOAP/XML/WSDLs (extremely powerful, but miserable to use) lost out to "pragmatic REST" and JSON/OpenAPI. (Though I know no one here is short on their own perspectives on this history — especially not Marsh.)

The proposal then is to sacrifice maximum possible ubiquity and maximum possible happiness for the greatest proportion of users in the combined okay and happy camps.

Possible improvements

I see a couple of potential avenues for expanding on the existing values and proposed objective.

Use cases

To make decisions more consistent and hedge against a specific decision failing to consider a use case, we might want to weigh any significant decisions against a predefined set of use cases. For example, we might break down use cases as:

• Authorship: approachability and ease
• Client implementation documentation: clarity and expressiveness for client developers
• Service implementation documentation: clarity and expressiveness for service developers and other internal stakeholders (architects, product managers, security auditors, designers, change advisory boards, etc.)
• Client code generation: expressiveness for modeling resources and operations in client-side code
• Service code generation: expressiveness for modeling routing, operations, resources, and validation in server-side code
• Test generation: adequate information to automatically generate tests to verify an implementation against an OpenAPI definition

One possible approach to make sure major decisions are considered against impact to each use case would be to assign one or more designated representatatives to each area, and ensure one representative per area is asked to weigh in on every major decision. (Not in any way as a replacement for the TSC — I would still expect generalists on the TSC to mediate conflicting interests and make final decisions.)

Because of the existing collaborative value that [all] interested parties can freely contribute ideas, we would still want to default to considering any additional use cases anyone brought to the table.

Opinions

I'm sure there's been much discussion in the past on how opinionated OpenAPI should be. It seems like we could almost reverse-engineer a consensus from what's made OpenAPI successful, and make it an official position. Perhaps something like:

• Favors resource-oriented APIs with predictable, hierarchical URIs which employ and honor HTTP semantics (level 2 APIs in the Richardson Maturity Model) over RPC-style APIs that tunnel over HTTP
• Favors JSON over other formats, but not a specific media type or approach to media types (e.g., does not favor JSON:API)
• Favors APIs employing uniquitous best practices, conventions, and design patterns as demonstrated in popular APIs and documented in style guides over practices without widespread acceptance

Scope

I think it would be beneficial to hone in the scope of what OpenAPI definitions really describe. In particular, I am not sure if all the design decisions in OpenAPI are consistent with an overall philosophy that an OpenAPI document specifies some subset of behavior a client may observe.

HTTP may tie our hands with respect to OpenAPI being a comprehensive contract for status codes or headers (since HTTP itself says that clients should handle all status codes and consider unrecognized headers valid by default). But when it comes to properties and parameters, it's unclear what OpenAPI is really saying if it doesn't define a parameter or sets additionalProperties: false for a JSON body. Are we intentionally leaving such things to meta-policies for robustness and compatibility or is OpenAPI intended to express something about these things as a "contract" language?

Practical considerations

With all that said, I think if we must pick a persona to prioritize, it has to be the API definition author. Why not consumers? I figure all the stakeholders who show up to these discussions will be doing their best to make consumers happy in the best way they know how, whereas the pure consumer probably won't show up at all to directly guide OpenAPI's evolution. And if API definition authors don't understand what they need to communicate to consumers, OpenAPI can't fix that.

My reasoning is pretty straightforward: for anyone to use OpenAPI, someone has to write OpenAPI definitions. So making authorship approachable, powerful, and moderately pleasant seems like the only way to avoid irrelevance. You could argue — as some have — that OpenAPI should be relegated to an intermediate format generated by code and annotations. To me, it seems clear this is a path to irrelevance, because whatever is the source of truth and lingua franca of APIs will eventually be used to directly generate documentation, client code, etc.

Thus, I think if one priority has to be chosen over others, it must be to keep OpenAPI approachable and powerful for those writing and editing definitions.

[darrelmiller]

Thank you, Dan, for such a well-reasoned and comprehensive contribution to the conversation. I fully agree with the objective of optimizing for the "okay" and "happy" camps. I think your use cases capture the primary value of OpenAPI. I'm going to punt on the longer conversation of OpenAPI as a "comprehensive contract". My high-level opinion is that the current offering is sufficiently flexible to allow API authors to be precise as they want to be.

I think the really interesting conversation comes in your last paragraphs. While I really do want to be completely in agreement with you, I see too much evidence that the value of an OpenAPI description is in its existence, not in the way it is created. Of the 6 use-cases you listed, 5 of them deliver value from a machine generated OpenAPI description. I talk to so many people who are inventing new ways of mechanically creating OpenAPI descriptions. People are sniffing traffic, doing static analysis of code bases, generating OpenAPI from higher level languages. Even the folks that are authoring OpenAPI by hand, are preprocessing them to achieve some goal that OpenAPI doesn't allow. People are working really hard to make folks happy who not want to have to create OpenAPI descriptions by hand.

While I understand the concern about treating OpenAPI as an immediate format will relegate it irrelevance. I don't believe that would be the outcome. TypeScript hasn't made JavaScript irrelevant. LESS and SASS hasn't made CSS irrelevant. There appears to be a new solution to generating CSS every week, while CSS just gets more capable. The JVM and CIL ecosystems have driven a community of many useful human facing languages. From my perspective, the real threat to all JavaScript/JVM/CIL is actually WASM. An intermediate format that has broad support is massively valuable because it drives interoperability. Machines don't express much of a preference. Humans are filled with opinions. Trying to build one language that will make everyone happy is a thankless task as JJ's framework highlights. Currently today, OpenAPI is clear winner in the intermediate format. What I see is everyone looking for something better as the human facing solution.

We definitely could take this signal as motivation to go solve the human facing problems that exist today. Our conversation on Thursday about OpenAPI's challenges with combining API descriptions is a great example. Being able to partition APIs descriptions due to organizational issues, or due to the desire to reuse API patterns would address a multitude of authoring concerns. However, I spent the weekend getting a deeper understanding of CADL by trying to describe the Mastodon API (https://github.com/APIPatterns/Moostodon/blob/main/spec/main.cadl). My takeaway from the experience is that the composability that has been implemented in CADL would be a mammoth task (pun intended) to achieve in OpenAPI. I can generate my OpenAPI from the CADL and do all the awesome OpenAPI things. CADL can do clever things because it relies on a compiler implementation. Relying on specific tooling is not something an intermediate format can do. I personally don't believe CADL, or any other higher level API design language is going to become the ubiquitous solution. I think we are going to have a proliferation of approaches, and that's OK because we can still win on the 5 out of 6 use-cases.

I think we have the opportunity to do some really cool stuff in mooncake that will address a range of OpenAPI issues. But I think when it comes to prioritizing work, we must acknowledge that many of our "happy" users are not writing OpenAPI by hand and we should be cautious trying to add design constructs that can be implemented much easier by upstream tools.

Thanks again for bringing your experience to this conversation.

[ahl]

This is a great discussion (of "mooncake" 🤣). I confess that in the 7 or so years of using OpenAPI I have been confused about the goals and intended audience for many of the changes.

One goal (I think that we all share) is to be able to express more extant, widely-used APIs in OpenAPI.

Another goal (which I do not think we share) could be to simplify the use of OpenAPI for programmatic consumers.

Goals are almost always in tension. For example, the former means that OpenAPI would be less prescriptive about what makes for a "good" API--arguably a significant downside! The latter conflicts with the goal of simplifying hand-generation of OpenAPI documents (.. and many people don't use an IDE in 2023!).

There are OpenAPI features for which I need to reverse-engineer the motivation (links...?). It would be clarifying to spell out the motivations clearly. For example, I would love to see OpenAPI express even more of how an API operates. What combinations of query parameters are valid vs. invalid? How can I get to the next page of a paginated endpoint? How are required checksum headers computed? These are currently all fodder for prose descriptions--fallible, imprecise, untested. The next version of OpenAPI could move those out of the description into precisely defined mechanism.

[handrews]

@ahl

The latter conflicts with the goal of simplifying hand-generation of OpenAPI documents

I think there is an ongoing healthy discussion about whether this is a goal. One school of thought argues for focusing on tooling support and letting tools (IDEs or otherwise) handle human-friendliness. The other emphasizes human-friendliness.

I think it would be good to pick one or the other, but the impact of either on both the community and tooling ecosystem is unclear.

If we leave UX to tools, the offered UX will vary dramatically, which could have some good outcomes but will likely leave a lot of people in difficult situations. It is non-trivial to change tools because OAS does not directly specify (most) tool behavior, resulting in lock-in despite it being a standard format.

if we emphasize UX for the format, there needs to be consideration on the adoption and support rate in tooling. While I think the lag in tool support for OAS 3.0 and 3.1 is not unusually large considering all of the factors, it is a significant lag. (although those who argue for more corporate control would do well to remember the lessons of IE6).

[kevin-postman]

@ahl take a look at the Workflow spec (https://github.com/OAI/sig-workflows). It may provide a lot of what your last paragraph is talking about. In particular.. it describes HOW to use an API via a series of steps that detail the incoming and outgoing variables among other things.

I might be biased.. but I lean towards the tooling aspect of API definitions. They are easy enough to read (for the most part).. but to me, the tooling.. automating code, docs, mocks, tests, etc is what makes API definitions more useful. We could probably argue that the extension capability allows for unforeseen tooling needs, so focus more on the UX aspect.

[darrelmiller]

@ahl Having spent a couple of years now going around in circles on the topic of "more authoring friendly for humans" vs "more comprehensive for machines", I have found my way moving towards the latter. This has been reinforced by two things:

1. I continually hear "in my company we do X preprocessing on the OpenAPI document to work around limitations" but every effort where we try to address those limitations results in a chorus of "that's too complicated for humans".
2. My experience of using https://microsoft.github.io/typespec/ which is not constrained by JSON/YAML syntax, provides a great authoring experience, and can still fully participate in the OpenAPI ecosystem.

I believe that if we are going to meet the goals of both an optimized human experience and an interoperable optimized machine experience we are going to need "API Design language(s)" and an "API Description" language. This pattern has played out over and over again in the tech space. There is concern from a number of people in the OpenAPI community that if we embrace the notion of design languages we will re-ignite the API description wars and OpenAPI will become an irrelevant implementation detail. I don't think that will be the case but certainly acknowledge the concern.