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

Microsoft detailed updates to its OpenAPI and JSON Schema tooling, including support for OpenAPI 3.2.0, which adds HTTP QUERY support, device flow support and streaming data, and JSON Schema 2020-12, which adds $dynamicRef/Anchor for recursive schemas. Microsoft said its Foundry platform imports OpenAI's OpenAPI description as a TypeSpec definition to generate SDKs, the Foundry API reference and server-side code, and performs contract testing. Microsoft argued that grounding probabilistic large language models in detailed specifications improves the reliability of AI-generated code.

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 https://spec.openapis.org/oas/v3.2.0.html brings updates to tags, improves performance through the added HTTP QUERY https://www.rfc-editor.org/rfc/rfc10008.html support, improves security through added device flow support https://www.rfc-editor.org/info/rfc8628/ , and adds support of streaming data https://spec.openapis.org/oas/v3.2.0.html streaming-sequential-media-types . 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 https://www.openapis.org/blog/2025/09/23/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 https://ai.azure.com/ 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 https://github.com/openai/openai-openapi/ 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. https://typespec.io/docs/emitters/openapi3/cli/ converting-openapi-3-into-typespec 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. https://ai.azure.com/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 https://github.com/microsoft/OpenAPI.NET 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 https://www.nuget.org/packages/Microsoft.aspnetcore.openapi , Swashbuckle https://www.nuget.org/packages/Swashbuckle.AspNetCore.Swagger/ , Azure API Management https://azure.microsoft.com/en-us/products/api-management , Microsoft Kiota https://aka.ms/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 https://github.com/microsoft/OpenAPI.NET/releases/tag/v3.0.0 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 https://dotnet.microsoft.com/en-us/apps/aspnet 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 https://github.com/dotnet/aspnetcore/issues/63754 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 https://typespec.io/ 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 https://github.com/microsoft/typespec/pulls?q=is%3Apr+is%3Amerged+label%3Aopenapi3%3Aconverter+merged%3A2025-08-01..2026-07-01 , 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 https://github.com/microsoft/typespec/pulls?q=is%3Apr+is%3Amerged+label%3Aemitter%3Aopenapi3+merged%3A2025-08-01..2026-07-01 , 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 https://json-schema.org/draft-07 . 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 https://github.com/microsoft/vscode/issues/26289 . Azure API Management Azure API Management https://azure.microsoft.com/products/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 https://learn.microsoft.com/en-us/azure/api-management/import-api-from-oas?tabs=portal 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 https://github.com/keegan-caruso and Martin Aeschlimann https://github.com/aeschli for the JSON Schema work in Visual Studio Code. - Mads Kristensen https://github.com/madskristensen for maintaining the JSON Schema Store project. - Timothée Guerin https://github.com/timotheeguerin for maintaining the TypeSpec project. - Youssef Fahmy https://github.com/youssef1313 for all his work on ASP.NET Core. - The Azure API Management engineering team. - The OpenAPI Initiative https://www.openapis.org/ , and maintainers. - The JSON Schema organization https://json-schema.org . - The Linux Foundation https://www.linuxfoundation.org/ . Build better APIs with OpenAPI Explore Microsoft’s OpenAPI documentation, tools, and SDK resources to learn how to work with OpenAPI-described APIs and build modern API development experiences.