HN
Today

Building a High-Performance OpenAPI Parser in Go

Speakeasy, facing shortcomings in existing Go OpenAPI parsers, unveils a new high-performance, type-safe library designed for massive scale. This technical deep-dive reveals its innovative reflection-based marshaller and "porcelain vs. plumbing" architecture. For Go developers tackling complex OpenAPI specs, this battle-tested solution promises robust reference resolution and a unified ecosystem for all their API tooling needs.

7
Score
1
Comments
#8
Highest Rank
7h
on Front Page
First Seen
Dec 18, 9:00 AM
Last Seen
Dec 18, 3:00 PM
Rank Over Time
8181516232026

The Lowdown

Speakeasy, a company dealing with thousands of OpenAPI specifications daily, details the engineering decisions behind their newly open-sourced Go library, github.com/speakeasy-api/openapi. This library aims to overcome the limitations of existing Go parsers, which often compromise either specification correctness or developer experience, providing a precise, high-performance solution for reading, validating, mutating, and transforming OpenAPI documents at scale.

  • Problem Statement: Existing Go OpenAPI libraries either sacrifice spec accuracy for speed or use untyped maps, hindering large-scale tooling development and refactoring. OpenAPI itself is complex, with dynamic types and recursive references.
  • Reflection-Based Marshaller: A core architectural choice that separates model definition from deserialization logic, allowing rapid iteration, central optimization, and support for multiple specification versions (OpenAPI 3.x, Swagger 2.0, Arazzo, Overlays) by defining new Go structs. It uses an intermediate Node representation for flexibility and metadata preservation.
  • "Porcelain vs. Plumbing" Performance: The library differentiates between internal "plumbing" (optimized for efficient storage and minimal memory allocations in hot paths) and a user-friendly "porcelain" public API of idiomatic Go structs. This ensures performance without sacrificing developer usability.
  • Type-Safe Dynamic Type Handling: Addresses OpenAPI's dynamic fields (e.g., a field being a string or an array) using generic abstractions like EitherValue and JSONSchema[Referenceable] to maintain strong type safety and consistency throughout the library.
  • Robust Reference Resolution: Features an engine for handling complex $ref pointers, including deeply nested, cross-file, and circular references. It maintains a document graph and stable identifiers, providing precise error reporting and enabling operations like bundling and inlining.
  • Unified Ecosystem Support: The flexible core allows native support for Arazzo (workflows) and OpenAPI Overlays (modifications) by sharing common building blocks, ensuring consistency and reusability across different specifications.
  • Comprehensive CLI Tooling: A CLI tool is provided, offering functionalities like bundle, inline, overlay, optimize, and sanitize, all built upon the same underlying Go packages, making library capabilities accessible for terminal use and CI pipelines. This new openapi Go library from Speakeasy represents a significant advancement for developers working with OpenAPI specifications, offering a robust, performant, and type-safe solution that addresses many long-standing challenges in the ecosystem. Its battle-tested nature and comprehensive feature set make it a compelling choice for serious API tooling development.