Trust is a key factor behind deciding which API specification format you should use. Should you define your API using AsyncAPI, OpenAPI, Smithy, or TypeSpec, just to name a few formats? Most of the time, you don’t even notice that you’re considering trust as a factor because it’s implicit. If your peers consider the format an industry standard, your level of initial trust is high. What happens is that over time, the trust might get eroded by any event where using the format creates a negative outcome. But what does it really mean to trust an API format? Stay with me to learn more.

This article is brought to you with the help of our supporter: Speakeasy.

Turn your API platform into an AI platform with Gram by Speakeasy. Create tools from OpenAPI, curate into custom toolsets, and deploy hosted MCP servers.

Start building with Gram

“Trust takes years to build, seconds to break, and forever to repair.” Or so the saying goes. Trust is very fragile. Especially when the possibility of technical negative outcomes is on the horizon. Imagine picking a technical solution only to find out it constantly fails and ruins your business. I bet you wouldn’t trust it for too long. Now, I’m not talking about a technical solution here. What I’m talking about is the set of rules on which you design and build your APIs. It’s the equivalent, in the non-technical world, to the laws you follow every single day. So, an API specification format is, in a way, many degrees of importance higher than any technical solution can be. What does it take for us to trust it, then?

Trusting an API specification format requires you to first trust the people who maintain it. To some extent, the API format is a reflection of who those people are and what they care about. Or, sometimes even more importantly, of the companies that those people represent. And this, to me, is where trust can begin to dilute. How can those people resolve the conflict of interest between creating the best possible open-source API format and pursuing whatever objectives their employers ask them to? In October 2025, from a total of 61 members of the technical steering committees of popular open-source API formats, about 54% are there acting for their employers. More than half of all committee members are there, supposedly, representing the interests of their employers. And this is the norm. To the point that some companies proudly publish it as a requirement on their job ads. “Foster influence across open-source, enterprise, and partner communities” was in a recent role description for a Head of Developer Relations job. It further explained that nurturing relationships with open-source specifications, to help influence future versions, was part of the role’s objectives. Companies big and small, many of them API vendors, sponsor open-source API specification formats. In exchange, they get a few seats at steering committees, making it possible to drive the direction of those projects.

To my relief, this behavior isn’t exclusive to the API industry. Neither is it something recent. No, across other areas, you can see that something similar has been happening for a long time. And people have been noticing it. Camille Fournier, the co-author of “The Manager’s Path,” shared in October 2025 that the quality of open-source software has been getting worse in part because of the direction driven by big companies1. This is exactly what I’ve been feeling. Take, for instance, the case of the well-known OAuth open-source project. In 2012, Eran Hammer, one of the authors of the OAuth 1.0 standard, resigned as the lead author and editor of OAuth 2.0. The main reason for his departure was “the strong and unbridgeable conflict between the web and the enterprise worlds,” he shared back then2. “When compared with OAuth 1.0, the 2.0 specification is more complex, less interoperable, less useful, more incomplete, and most importantly, less secure,” he added, concluding that “the resulting specification is a designed-by-committee patchwork of compromises that serves mostly the enterprise.” A very sad result for something as promising as the second iteration of the popular OAuth standard.

Back to the API industry, not all is bad, fortunately. Even though there are many companies involved in API formats, some of the people who represent them are trustworthy. At least, judging by their public opinion about company-led open-source contributions. I asked a few people how they’d react if their employer asked them to make a contribution that would go against their personal values. It could be something as simple as voting against a certain issue or reviewing a PR negatively. Or, it could involve more sophistication, like slowly adding code and pushing PRs that would drive their employer’s agenda forward. Most people shared they would simply refuse, even knowing they’d probably be let go. To me, this is a clear sign of their maturity and shows they can understand and avoid any potential conflicts of interest.

So, what do you really mean when you say you trust an API specification format? Do you trust that its members somehow dissociate themselves from the objectives their employers have for them? Or, that their employers are thinking about your best interests and not theirs? Or something else? Perhaps it’s easier to trust an API format that is driven by a single company. Specification formats such as Smithy and TypeSpec aren’t announced as being community-led standards. What they’re both fully open about is that they’re backed by large companies. Amazon created Smithy as an evolution of its existing AWS service model format. It then open-sourced it in 2020 under the Apache 2.0 license. Even though it’s an open-source project, it’s clear what its origins are and who’s behind it. There are no false expectations. TypeSpec, also an open-source project, is more explicit about the company behind it. Its license has Microsoft as the copyright holder, its GitHub repo is under the Microsoft organization, and most of its blog posts are signed by Microsoft employees. The posture, in these two API formats, is completely different from that of the others. There’s clearly a more enterprisey feeling when you access these projects and their documentation. In this sense, it feels easier to trust Smithy and TypeSpec than it does to trust many of the other API formats. Does that mean you should trust them?

I would treat an API format as any other product because trust isn’t given, it’s earned. What matters to me are a few core traits: open governance, a transparent roadmap, technical rigor, clear documentation, reliable tooling, and genuine vendor neutrality. The first thing I check is whether its governance and roadmap are public. Are there public discussions? Transparent versioning with a clear explanation of the updates? Openness to external opinions and requests? If so, it’s a good sign. Something related is the ability to maintain vendor neutrality. Even if many companies sponsor an API format, they shouldn’t be able to control its roadmap. With that, I’d be closer to trusting an API format, but I’d still look at its level of technical excellence. If the documentation is confusing, there are problems with the specification, and people can’t use it to fulfill their use cases, then I’d find it hard to trust. Finally, I’d be looking for up-to-date tools like SDK generators, ways of generating documentation, and linters. If the tools aren’t there, it’s hard to believe the format can support production use.

Overall, trust in an API format has many faces. Some of them are easy to spot, while others are hard to identify. Vendor neutrality, as I wrote, isn’t easy to verify. That’s why I think you should pay special attention to it. It’s easy to trust an API format and, later on, find that its roadmap is being driven by one or more companies to feed their private interests. Whether or not you should use an API format is obviously your call. But at least you know that choosing the wrong format can have a longer-term negative impact on your business.

1

“Have an idle speculation lately that the quality of OSS has, by and large, gotten worse thanks to the super-corporate Foundations, which, as a side effect of enabling big companies to work together in public (good), creates a lot of big company-looking OSS (not so good),” shared Camille Fournier on Bluesky on October 20, 2025.