Notifications
Clear all
Topic starter
22/06/2026 10:20 am
TL;DR: A single OpenAPI spec can be turned into a typed intermediate representation that drives language-specific SDK generation, reducing drift by making the spec the source of truth and the emitter the only language-specific layer, according to WorkOS. The real lesson is that generated code quality depends on disciplined schema design, not just tooling.
NHIMG editorial — based on content published by WorkOS: How to build a custom SDK generator with oagen
Questions worth separating out
Q: How should teams prevent drift when generating SDKs from OpenAPI specs?
A: Treat the OpenAPI spec as the single source of truth, resolve it into a typed intermediate representation, and make every language backend consume that same model.
Q: Why do typed intermediate representations matter in code generation pipelines?
A: A typed IR makes schema meaning explicit before rendering begins, which reduces ambiguity and catches unsupported variants early.
Q: How do teams know if a generator is safe enough to maintain long term?
A: Look for exhaustive type handling, deterministic output, and fixture-based tests that cover edge cases such as nullability, unions, and pagination.
Practitioner guidance
- Treat the spec as the control plane Make the OpenAPI document the only approved source of truth for method names, types, and service grouping, then forbid downstream hand edits to generated clients.
- Enforce exhaustive emitter coverage Use discriminated unions and compile-time checks so a new schema variant fails the build until every renderer branch is updated.
- Test generator output with golden fixtures Add fixture specs for edge cases such as unions, nullable fields, pagination, and enums, then compare emitted files byte for byte in CI.
What's in the full article
WorkOS' full article covers the operational detail this post intentionally leaves for the source:
- Step-by-step emitter code for Python, including how the generator renders models, enums, and service clients.
- Golden-file test examples that show how to validate generator output against fixture specs.
- Implementation details for request-body handling, pagination, retry policy emission, and method-name resolution.
- Practical notes on building and using a custom SDK generator around oagen's parse, resolve, and diff commands.
👉 Read WorkOS' guide to building a custom SDK generator with oagen →
OpenAPI SDK generation and typed IR: what teams need to know?
Explore further
22/06/2026 11:11 am
Typed contract generation is a governance pattern, not just a developer convenience. The article shows that a spec resolved into a typed IR becomes the single place where meaning is fixed before language-specific output is produced. That same pattern maps cleanly to identity programmes that need consistent treatment of service accounts, API credentials, and autonomous tool access across systems. When the contract is authoritative, downstream drift becomes a governance problem instead of a tooling mystery. Practitioners should treat typed contract enforcement as control architecture, not formatting.
A few things that frame the scale:
- Only 44% of developers are reported to follow security best practices for secrets management, exposing a significant developer behaviour gap, according to The State of Secrets in AppSec.
- Fragmentation matters too, because organisations maintain an average of 6 distinct secrets manager instances, according to The State of Secrets in AppSec.
A question worth separating out:
Q: What is the difference between a source schema and generated SDK code?
A: The source schema defines the contract, while generated SDK code is an implementation artefact derived from that contract. If teams edit generated clients by hand, they reintroduce drift and make lifecycle control harder across every language target.
👉 Read our full editorial: OpenAPI SDK generation shifts the source of truth into typed IR
