From standards to software: Microsoft’s ongoing work on OpenAPI and developer tooling

Today I’m excited to share several updates across Microsoft products, open-source projects, and services related to OpenAPI and JSON Schema support.

Taken together, these updates show how specifications are moving from background plumbing to active developer experience infrastructure: they help teams describe APIs more accurately, build better tools, and make AI-assisted development more reliable.

Why OpenAPI and JSON Schema matter for AI-assisted development

Open specifications enable interoperable ecosystems of products, tools, and services, while giving engineering teams the precision they need to build consistently across implementations. Microsoft has long contributed to specifications such as OpenAPI and remains committed to advancing them as the foundation for better engineering practices.

In the age of AI-assisted and agentic development, that precision matters even more. Because large language models are probabilistic, grounding their work in detailed specifications improves the reliability of generated code.

What is OpenAPI and why developers use it?

OpenAPI is a language-agnostic specification for describing REST APIs in a way that both humans and tools can understand. For more than a decade, it has been the de facto standard for REST API descriptions, backed by a broad community of vendors, tool builders, and practitioners.

OpenAPI 3.2.0: What’s new for API developers

OpenAPI 3.2.0 brings updates to tags, improves performance through the added HTTP QUERY support, improves security through added device flow support, and adds support of streaming data. These improvements give API producers more precise ways to describe modern, AI-ready API patterns.

You can learn more in the announcing OpenAPI v3.2 blog post.

JSON Schema 2020-12: Key improvements for OpenAPI and API design

Improving OpenAPI support also led us to improve support for JSON Schema. The latest version of JSON Schema brings support for $dynamicRef/Anchor which finally solves recursive schemas without brittle $ref chains. It also clarifies vocabulary handling and improves interoperability. Better schemas mean a greater ability for you to catch issues earlier on!

Case study: How Microsoft Foundry uses OpenAPI, TypeSpec, and JSON Schema

Foundry provides a useful example of how specifications, converters, schemas, editors, gateways, and generated assets can reinforce one another across a large platform.

Microsoft Foundry is a platform for building AI and agentic solutions, with thousands of models from many providers, evaluation and fine-tuning capabilities, agent building and hosting, and more.

Foundry exposes its own REST APIs for platform-specific capabilities, while also maintaining full fidelity with OpenAI’s REST APIs so customers can move solutions between them without rebuilding from scratch.

This is where strong specifications and the tooling around them helped accelerate that work, control implementation costs, and improve overall quality.

OpenAI maintains an OpenAPI description for everyone to use, which it also uses internally to generate software development kits (SDKs) and more. The Foundry developer experience team imports that description as a TypeSpec definition using the TypeSpec convert tool.

Using those definitions, Foundry service teams can describe their additional APIs in TypeSpec and use the consolidated model to:

• Generate SDKs.
• Generate the Foundry API reference.
• Generate server-side code.
• Perform contract testing to ensure highfidelity with the OpenAI REST API.

The developer experience for engineers across the platform is also supported by JSON Schema and Schema Store integration in Visual Studio Code, while parts of the service infrastructure rely on API Management under the hood.

Microsoft investments in OpenAPI, JSON Schema, and developer tooling

Over the last year, multiple teams at Microsoft have worked to bring products and services up to date with the latest developments in the OpenAPI and JSON Schema space. The examples below show how that work is landing across libraries, frameworks, editors, API platforms, and AI developer experiences.

.NET

Microsoft.OpenAPI

Microsoft.OpenAPI is the main .NET library for parsing, building, and serializing OpenAPI descriptions. A shared implementation helps the ecosystem avoid duplicating the complex work required to fully support the specification.

This library provides a foundation for ASP.NET Core OpenAPI integration, Swashbuckle, Azure API Management, Microsoft Kiota, and hundreds of product teams at Microsoft.

After OpenAPI 3.2.0 was released, we shipped a new Microsoft.OpenAPI version with support for the updated specification so the broader ecosystem could adopt the new capabilities. That work, along with countless contributions since, was done by community members like you!

ASP.NET Core in .NET 11

ASP.NET Core is Microsoft’s open-source, cross-platform framework for building modern web apps, services, and APIs with .NET. It gives developers a high-performance foundation for creating cloud-ready applications that can run on Windows, Linux, and macOS.

ASP.NET Core in .NET 11 continues to make OpenAPI a first-class part of the web API developer experience. In this release, ASP.NET Core adds support for OpenAPI 3.2.0 by default, built on Microsoft.OpenAPI, giving developers a clear path to describe and validate modern API patterns.

The list of new capabilities was informed by the community and includes support for:

• HTTP QUERY operations.
• Server-Sent Events (SSE) streams.
• Accurate binary and file result response schemas.
• C# union-typed responses.
• And many more improvements!

Note: .NET 11 will become generally available in November 2026 and is currently in public preview.

TypeSpec

TypeSpec is Microsoft’s open-source language for designing APIs in a concise, reusable, specification-friendly way. Teams can define their model once in TypeSpec and generate OpenAPI descriptions, JSON Schemas, documentation, and client or server code from that source of truth.

Over the last year, we’ve greatly improved the OpenAPI to TypeSpec convert tool, enabling lift-and-shift production scenarios where API producers and architects can build on existing API investments while improving their design experience.

We’ve also added support for emitting OpenAPI 3.2.0 descriptions and implemented new OpenAPI capabilities, so once you’re done designing your API, you can get high-fidelity OpenAPI descriptions and use them in your favorite tool/platform.

Visual Studio Code

Support for JSON schema 2020-12

Developers spend a lot of their time in the integrated development environment (IDE). When reviewing or authoring any JSON document, they expect that environment to catch simple mistakes and provide accurate autocompletion.

Visual Studio Code uses a JSON language server to provide syntax highlighting and validate documents against JSON Schema. Until recently, that language server only supported JSON Schema Draft 07, a specification published back in 2018.

This meant that if your JSON document relied on a schema that used more modern capabilities from JSON Schema 2019-09 or 2020-12, some validation rules could be ignored or fail entirely. OpenAPI 3.1 and 3.2 are good examples because their schemas rely on JSON Schema 2020-12 to validate that a document is properly structured.

Since version 1.130.0, Visual Studio Code now supports JSON Schema 2019-09 and 2020-12, offering the latest validation experience you could ask for any JSON document.

Built-in OpenAPI and schema validation in Visual Studio Code

In version 1.140.0, Visual Studio Code also added built-in schema mappings for OpenAPI, Overlay, and Arazzo documents.

Combined with support for newer JSON Schema versions, these built-in mappings give known JSON documents, including OpenAPI 3.2 documents, structural validation in Visual Studio Code without requiring a third-party extension.

Help improve JSON Schema Store integration in Visual Studio Code

The JSON Schema Store is an open-source catalog of schemas for common JSON documents. Each catalog entry can also include metadata such as the filename patterns associated with that schema.

Integrating the JSON Schema Store would let Visual Studio Code automatically select and validate against the appropriate schema based on known filename patterns, without requiring manual configuration or a $schema property. If you’d like to see this capability, please upvote this issue.

Azure API Management

Azure API Management helps teams publish, secure, govern, monitor, and expose backend APIs, including REST and AI APIs, through managed gateways and developer portal experiences powered by OpenAPI descriptions.

Until recently, API Management only supported up to OpenAPI 3.1 for ingestion and 3.0 for publishing. With the support for OpenAPI 3.2, customers can expand how they define and publish APIs and integrate with other platforms. This update also improves support for importing OpenAI v1 model APIs, making it easier to automate API creation and manage traffic to OpenAI models through AI Gateway capabilities in API Management that thousands of Azure customers rely on.

API Management is deploying OpenAPI 3.2.0 support across Azure regions and service tiers.

Recognizing the contributors advancing the OpenAPI ecosystem

Thank you for using, maintaining, and contributing to the specifications, libraries, tools, and services that make this ecosystem work. OpenAPI succeeds because people across organizations keep improving both the standard and the developer experiences built on top of it.

Special thanks to:

• Keegan Caruso and Martin Aeschlimann for the JSON Schema work in Visual Studio Code.
• Mads Kristensen for maintaining the JSON Schema Store project.
• Timothée Guerin for maintaining the TypeSpec project.
• Youssef Fahmy for all his work on ASP.NET Core.
• The Azure API Management engineering team.
• The OpenAPI Initiative, and maintainers.
• The JSON Schema organization.
• The Linux Foundation.