Everyone — especially people obsessed with SEO — loves a clickbait title (and, if you’re British, some Monty Python quotes). In this post, we are meeting that need by asking whether the emergence of TypeSpec will reignite the Specification Wars, a question posed at the 2024 Austin API Summit.

For the uninitiated, the Specification Wars were a “Rock-Em, Sock-Em” style contest in the 2010s — played out in the API media — on which API description language would become the most prevalent. While some of the details are hyperbole, which is what passionate technologists and journalists tend to do, there was a healthy debate on which API description language best represented the needs of the API economy, and rightly so. Having a language that correctly represents API signatures (the aggregate of the attributes of a given operation at an API with specific parameters) is critical to successfully describing an API so it can be understood by humans and parsed by machines. The Specification Wars had several protagonists, including RAML, API Blueprint, and Swagger, with Swagger coming out on top before becoming OpenAPI.

OpenAPI has been the most prevalent description language for several years, and its reach in the API economy is self-evident. However, where there’s smoke, there’s fire. Why did Microsoft create a new description language when it is a member of the OpenAPI Initiative and therefore literally bought into the development of the OpenAPI Specification?

Where Does TypeSpec Fit?

In our post introducing TypeSpec, we discussed the nuts and bolts of TypeSpec and how Microsoft created the language to foster design-first API development. We touched on the fact that OpenAPI was perceived by the TypeSpec protagonists at Microsoft as being overly complex, with a high barrier to entry in terms of required knowledge and not serving alternative protocols like gRPC. In his 2024 Austin Summit talk, Gareth Jones took this argument further and, without decrying the benefits of OpenAPI, showed an example of the inherent complexity of OpenAPI when publishing a more intricate API.

Graphic showing the complexity of OpenAPI description documents based on API complexity.

One key point is the complexity and size of OpenAPI description documents when they are dereferenced and consolidated. In Gareth’s words:

“If we’re talking about working with these files, particularly for design and governance activities, well, if my files are in the hundreds of thousands to, at the far end, millions of lines of consolidated OAS [OpenAPI Specification], I just can’t work with that sort of information. It’s not just in the bank of me being able to process it as a human.”

You could argue that such experiences with OpenAPI can be dealt with through refinement, and developing and tuning the tooling in a way that helps humans cope with volume. However, the OpenAPI tooling ecosystem is diverse and one would expect that an organization with the resources of Microsoft would have been down this rabbit hole. In Gareth’s words, this is why Microsoft reached for the tool of abstraction to reduce cognitive baggage. TypeSpec is the result of that exercise, along with capturing common design patterns. It’s a simpler design methodology that attempts to ease complexity using a (more-or-less) unified toolset.

Why TypeSpec Works For Users

From the get-go, TypeSpec has attempted to provide almost everything you need to design your APIs. You start with the specification itself, an NPM-based CLI, plugins for both Visual Studio and Visual Studio Code, and detailed instructions on creating your design and extending it using built-in libraries. There are some parallels to this approach in the AsyncAPI world: While AsyncAPI has always been open source and has a large tooling community, the AsyncAPI Initiative has done a great deal to provide centralized tooling that supports developers and designers using the specification.

While this does not solve every problem out there, what it does shoot for is a (relatively) simple means to get multiple teams started on design. Despite looking like code, TypeSpec is a design language. One of its primary goals is to help users create their APIs using something feature-rich and extensible in the same way code is. It also provides a one-size-fits-all methodology across protocols. You can create (within the bounds of the protocols, obviously) OpenAPI descriptions, Protobuf, gRPC, or, with the right plugins, anything else relevant to your community.

How OpenAPI Can Do What TypeSpec Does

Where does the emergence of TypeSpec leave OpenAPI? Well, for the moment, OpenAPI is still the most popular API description language in the API economy. Its richness and extensibility make its application wide for API consumers, and with the right tooling, it allows them to service their needs across the API lifecycle. However, this richness and extensibility comes at a cost, namely that for many developers and designers, working with OpenAPI can be hard. Implementation in tools is also almost always opinionated as there is so much room for interpretation, especially when you consider the reliance on two versions of JSON Schema across the last two minor versions.

We’ve discussed support from the specification maintainers in the tooling world, and in this case, the OpenAPI Initiative could replicate the early success of TypeSpec and AsyncAPI by offering more tools that are centrally maintained and provided and reflect the “state of the art” for the description language. A good example of such a project is OASComply, which will provide a compliance parser for OpenAPI descriptions created by an API provider. Such work can only serve to strengthen the community and provide additional affordances in the existing, rich ecosystem.

The next major version of OpenAPI, codenamed “Moonwalk“, is also in progress. One complaint leveled at OpenAPI is that JSON Schema increases complexity for many users. It remains to be seen whether Moonwalk will keep its reliance on JSON Schema or opt for something else. If it does, we could see a shift to new toolsets with different syntaxes and affordances for the community.

Let’s Call It a Draw: The Future of API Description Languages

The evidence suggests that the Specification Wars are, for now at least, consigned to history. OpenAPI is still the dominant API description language, and the community behind it serves to support the continued growth of the API economy.

TypeSpec is an attempt to combine the design-first and code-first worlds into something that works across both methodologies and reduces cognitive load for designers. You get the convenience and flexibility of an API design approach that “looks like code” and is eminently reusable and extensible, with a means to support API governance embedded in the tools themselves. You also get support for tools and description languages already in the existing API landscape, especially for the OpenAPI Specification. The TypeSpec approach also means a general decrease in complexity, which, for Microsoft, eases its use across the organization.

However, TypeSpec does not specifically seek to replace OpenAPI. It provides a bridge between design-first tools intended to simplify the design process and the OpenAPI toolchain. API consumers still need the means to consume an API description using a rich, expressive language, and OpenAPI delivers just that. We can all rest assured that the war is over. (For now…)