Building Speakeasy
OSS Release: OpenAPI Parser
Tristan Cartledge
August 12, 2025 - 4 min read
Today we’re excited to announce the release of our OpenAPI parser library — a comprehensive Go library for working with OpenAPI 3.0.x and 3.1.x specifications, Arazzo workflow descriptions, and OpenAPI Overlay files that has been battle-tested on thousands of real-world API specs.
Why we built this parser
At Speakeasy, we process thousands of OpenAPI specifications from companies across all industries and sizes through our core SDK generation platform. More recently, through Gram — our platform for building MCP (Model Context Protocol) servers — we’ve encountered even more diverse specifications in varying states of completeness and correctness.
These specs come in all shapes and conditions — some perfectly valid, others with quirks, gaps, or outright errors that need to be handled gracefully. Gram, in particular, has been a catalyst for pushing our parsing capabilities further, as it needs to work reliably with imperfect specifications while automatically generating functional MCP servers.
We needed a parser that could work with imperfect specs while providing the tools to improve them over time. This is especially important for API tooling that helps developers enhance their specifications incrementally, whether they’re generating SDKs or building MCP servers.
Core capabilities
The library provides comprehensive functionality for working with OpenAPI documents:
- Parsing and validation: Full support for OpenAPI 3.0.x and 3.1.x with built-in validation
- Document traversal: Powerful walking API to iterate through specific elements
- Reference resolution: Intelligent handling of
$refreferences, including circular references - Document manipulation: Create, modify, and transform OpenAPI documents programmatically
- Upgrading: Automatically upgrade OpenAPI 3.0.x documents to 3.1.x
- Type safety: Strongly typed Go structs that closely mirror the OpenAPI specification
Getting started
Here are some examples of what you can do with the parser:
Advanced features
The parser includes several advanced capabilities that set it apart:
Lazy reference resolution: References are resolved on-demand, giving you fine-grained control over when and how references are loaded. This improves performance when working with large documents where you only need specific parts.
Circular reference handling: Properly detects and handles circular references in schemas without infinite loops or stack overflow errors.
Extension support: Full support for OpenAPI extensions (x-* fields) with type-safe access patterns.
Memory efficiency: Optimized for working with large specifications while using minimal memory, important when processing hundreds of documents.
Beyond OpenAPI: Arazzo and Overlays
While OpenAPI documents define individual API endpoints, this library also supports two important extensions to the OpenAPI ecosystem:
Arazzo workflow specifications allow you to describe chains of API calls and complex workflows. Instead of just defining what endpoints exist, Arazzo lets you describe sequences like “authenticate → create user → get user → delete user” where the output of one call feeds into the inputs of another. This is particularly powerful for testing API workflows and building integrations across multiple services.
OpenAPI Overlays provide a way to modify existing OpenAPI documents without directly editing the original files. Overlays are separate documents containing instructions for updating, adding, or removing parts of an OpenAPI specification. This is invaluable for managing different versions of your API documentation, applying organization-specific customizations, or maintaining separate internal and external versions of your API specs.
Both specifications integrate seamlessly with the core OpenAPI parsing functionality, giving you a complete toolkit for working with modern API specifications.
What’s next
This release represents our foundational parsing capabilities across the OpenAPI ecosystem, but we have exciting plans ahead:
- Enhanced tooling integration with our CLI for validation and transformation workflows
- Additional utilities for common manipulation tasks across all supported specifications
- Support for emerging OpenAPI specification features as they’re released
- Community-driven improvements and extensions
Open source and community-driven
This library is fully open source and we welcome contributions from the community. Whether it’s bug reports, feature requests, or pull requests, we’re excited to collaborate with developers who are building the future of API tooling.
The codebase has been designed with contributors in mind — clean architecture, comprehensive tests, and clear documentation make it easy to understand and extend.
Try it out
The OpenAPI parser is available now on GitHub. Get started by checking out our documentation and examples, and let us know what you build with it!
We’re excited to see how the community uses this library to build better API tooling. This release represents years of learning from real-world API specifications, and we can’t wait to see what innovative solutions the community creates with it.