TypeSpec vs OpenAPI: which API definition language fits agent-era platforms

You're deciding how to define your APIs. The choice used to be OpenAPI or hand-written docs. Now there's a third option gaining ground: TypeSpec, Microsoft's API definition language that compiles down to OpenAPI, JSON Schema, or Protobuf (which in turn feeds gRPC toolchains).

This piece is for platform engineers, API architects, and heads of engineering picking a specification approach for a new API — or reconsidering an existing one because AI agents are now consuming the spec, not just human developers.

The short version: OpenAPI is the interchange format the ecosystem runs on. TypeSpec is a higher-level authoring language that generates OpenAPI (and other outputs) from more concise, reusable source. They're not really competitors — one produces the other. The real question is where in your workflow the source of truth lives, and how much your team writes by hand.

How OpenAPI works

OpenAPI is a specification format for describing HTTP APIs. You write a YAML or JSON document that declares your endpoints, request and response schemas, authentication, and error contracts. The current version is 3.2 (released September 2025), which builds on 3.1's alignment with JSON Schema 2020-12.

An OpenAPI document is the contract. The ecosystem around it is enormous: Swagger UI renders it as interactive docs, Redoc produces a different style of reference, openapi-generator and tools like Speakeasy and Fern generate SDKs, contract-testing tools like Prism mock the API, and validators like Spectral enforce house style. Every major HTTP framework has some way to emit or consume OpenAPI.

You write OpenAPI in one of two ways. Design-first: hand-author the YAML and generate server stubs and clients from it. Code-first: annotate your handlers and let the framework emit the spec at build time. Both approaches have real production users, and both have failure modes — hand-written specs drift from the code, generated specs inherit whatever inconsistencies the code has.

We've covered the OpenAPI ecosystem in depth in what is OpenAPI and OpenAPI specification best practices.

How TypeSpec works

TypeSpec is a domain-specific language for describing API shape. You write .tsp files that look more like TypeScript than YAML — models, operations, decorators, namespaces. A compiler emits OpenAPI 3.0/3.1, JSON Schema 2020-12, or Protobuf from the same source.

Microsoft built TypeSpec (originally CADL) internally to manage the scale of Azure's API surface. Azure has 200+ services and thousands of operations, and hand-authoring OpenAPI for all of them produced inconsistency, duplication, and drift. TypeSpec's pitch is that you write the API shape once, in a language designed for it, and the machine produces the interchange formats.

A small TypeSpec example looks like this:

model Pet {
 id: string;
 name: string;
 species: "cat" | "dog" | "bird";
}

@route("/pets")
interface Pets {
 @get list(): Pet[];
 @post create(@body pet: Pet): Pet;
}



Compile it and you get an OpenAPI document that would take three to four times the lines to write by hand. The library system lets you package common patterns — pagination, error envelopes, auth schemes — as reusable modules that enforce consistency across teams.

TypeSpec is open source, actively developed, and used in production by Azure. The ecosystem outside Microsoft is smaller but growing.

Comparison

When to choose OpenAPI

Stay with OpenAPI as your primary authoring surface when:

• You have one API and it's stable. The TypeSpec authoring win compounds across many APIs. For a single well-scoped service, hand-authored OpenAPI or a framework's code-first emitter is fine.
• Your team already ships OpenAPI reliably. If you have working drift detection in CI, Spectral rules that enforce house style, and code-first tooling that keeps the spec current, adding a compilation step for its own sake is friction.
• Downstream tooling is the constraint. If you need to hand your spec to a specific generator, validator, or documentation platform, generating OpenAPI directly means one fewer thing that can go wrong in the pipeline.
• You're publishing a public API. External developers expect to read OpenAPI. Some will import it into Postman, some into their own generators. Publishing OpenAPI as the source of truth removes a layer of translation.
• Your API surface is HTTP-only. TypeSpec's multi-protocol output is a real advantage if you're also shipping gRPC or event schemas. If you're not, that advantage doesn't apply.

When to choose TypeSpec

Reach for TypeSpec when:

• You have many APIs and they need to be consistent. This is TypeSpec's original problem. Libraries enforce that every service's error envelope, pagination pattern, and auth scheme looks the same — without a governance forum reviewing every PR.
• The same shapes need to appear in multiple protocols. If a team ships both an HTTP API and a gRPC service backed by the same models, defining them twice is where drift starts. TypeSpec emits OpenAPI and Protobuf from one source, so the gRPC toolchain and the HTTP toolchain start from the same models.
• Your OpenAPI files have gotten unmanageable. Past a few thousand lines, hand-authored OpenAPI becomes hostile to change. Refactoring is difficult, common patterns get copy-pasted, and $ref structures ossify. TypeSpec's model composition and inheritance handle this better.
• You're operating at platform scale. Microsoft built this for a reason. If you have dozens of teams shipping APIs against shared standards, TypeSpec's library model is a governance mechanism, not just an authoring convenience.
• Your team is comfortable with a compilation step. TypeSpec adds one. If your build pipeline already generates code from schemas — Protobuf, GraphQL, database migrations — one more compiler is easy. If it doesn't, the friction is real.

What agents change

Both options produce OpenAPI in the end. But what they produce, and how much of your product surface it covers, matters more than the authoring format when agents are the consumer.

Agents don't read OpenAPI directly at runtime. They call tools, which are generated from the spec. If your OpenAPI describes 2% of what your product can actually do — because most product capability sits behind the UI, not the API — then TypeSpec vs OpenAPI is a rounding-error debate. The gap you need to close is between your API surface and your product surface, not between two ways of writing the API surface you already have.

The agent-relevant differences between the two:

• Consistency compounds. Agents make many more tool calls than humans make API calls, and they're less forgiving of inconsistency. A codebase where every endpoint uses the same error envelope, the same pagination pattern, and the same auth model gives you tools that behave predictably. TypeSpec's library model enforces this more strictly than Spectral rules on hand-written YAML.
• Emit fidelity matters. Tool generators that turn OpenAPI into agent tools depend on the spec being accurate and complete. Missing response schemas, vague additionalProperties, and un-annotated parameters produce tools the model can't call correctly. Both approaches can produce good specs — TypeSpec makes it slightly harder to produce a bad one.
• Neither fixes drift on its own. OpenAPI spec drift — where the spec and the running code diverge — is a runtime problem, not an authoring one. TypeSpec's compilation catches its own consistency errors, but it doesn't verify the API actually behaves the way the spec says. You still need contract testing and runtime canaries.

How Pontil fits

Both TypeSpec and OpenAPI assume the API surface is the interface. That assumption held when human developers were the consumers. For agents, it usually doesn't — the API surface is a small fraction of what the product does, and closing that gap by hand-writing more OpenAPI (or TypeSpec) is a multi-year project.

Pontil is a Tools-as-a-Service platform. We generate agent tools directly from your codebase, not just from your OpenAPI spec — which means the tools reach product capability that never made it into the API in the first place. Where you already have OpenAPI (however you authored it), we consume it. Where the capability lives only in the code, we scan for it. Either way, the tools stay current as the product changes, execute as the authenticated user, and honour the permissions the UI already enforces. Your spec choice becomes an input, not the ceiling.

What we'd choose

For a new API being built from scratch by a team that also owns other services and cares about consistency across them: TypeSpec. The library model pays back within the first few APIs, and generating OpenAPI as a build artefact keeps the ecosystem tooling working.

For a single existing API where the spec is already reliable and the team ships OpenAPI without pain: stay on OpenAPI. The migration cost is real, and you'd be adding a compilation step to solve a problem you don't have.

For a platform with dozens of services and a governance problem: TypeSpec, and treat the library layer as the actual standardisation mechanism. Style guides are advisory; compiler errors are not.

The question isn't which format wins. It's whether your authoring pain is bad enough — and your API portfolio big enough — to justify adding a compilation step. If it is, TypeSpec is the strongest option in the space. If it isn't, OpenAPI is still the format the ecosystem runs on.