Engineering Under the Hood: Building a High-Performance OpenAPI Parser in Go Tristan Cartledge December 12, 2025 - 12 min read Engineering
At Speakeasy, we process thousands of OpenAPI specifications every day across a wide range of teams and industries. These specs drive our production-ready SDKs, Terraform providers, and a growing set of internal tools.
That volume exposes every sharp edge of OpenAPI. From small hand-written specs to multi-megabyte machine-generated schemas with deeply nested references and vendor extensions, we’ve seen almost every way an OpenAPI document can go wrong.
As our platform grew, we hit the limits of existing Go libraries. Some were fast but modeled the spec loosely, making it hard to build correct tooling on top. Others were closer to the spec but used untyped maps everywhere, which made large refactors and static analysis painful.
We needed something different: a library that could be both a precise model of the specification and a high-performance engine for reading, validating, mutating, and transforming specs at scale.
So we built our own. Today, we’re introducing github.com/speakeasy-api/openapi , a comprehensive set of packages and tools for working with OpenAPI, Swagger, Arazzo, and Overlay Specification documents.
While our release post covers the high-level features, this article focuses on the engineering: the core abstractions, performance decisions, and tradeoffs that make this library a strong foundation for any OpenAPI tooling written in Go. If you’re choosing an OpenAPI library for Go today, our goal is that this post gives you enough signal to make this your default choice.
The Challenge: OpenAPI is Hard
OpenAPI is a deceptively complex specification. It has evolved significantly over time (2.0 to 3.2), supports dynamic types (fields that can be a string or an array), and relies heavily on JSON Schema, which allows for recursive and circular references.
Existing Go libraries often struggle with these edge cases, either by simplifying the model (losing accuracy) or by exposing a raw, untyped map structure (losing type safety). We needed a solution that offered both correctness and developer experience.
... continue reading