How freee Migrated 33,000 Lines of OpenAPI YAML to TypeSpec

TypeSpec is a Microsoft-developed API definition language that uses TypeScript-like syntax while generating OpenAPI Specification. The freee billing team successfully migrated their largest internal API definition — a 33,000-line OpenAPI YAML file — to TypeSpec. This case study highlights significant improvements in readability and maintainability for schema-driven development.

📑Table of Contents

1. What is TypeSpec — Features of Microsoft’s API Definition Language
2. Background of the Migration — Challenges with 33,000 Lines of OpenAPI YAML
3. Migration Decision Points — Comparing Continued OpenAPI vs TypeSpec Adoption
4. Actual Migration Steps and Development Flow
5. Effects After Introduction and Remaining Challenges
6. freee’s TypeSpec Usage Examples and Recommended Points

---

What is TypeSpec — Features of Microsoft’s API Definition Language

TypeSpec allows developers to describe API schemas in a more human-readable format. Key features include:

• TS-like syntax: Familiar to TypeScript developers for concise model and operation definitions
• OpenAPI output: Generates standard OpenAPI YAML/JSON, ensuring compatibility with existing toolchains
• Built-in Linter/Formatter: Maintains code quality automatically
• Code generation support: Works seamlessly with generators like ogen (Go) and orval (React)

The spend management team at freee has used TypeSpec for over 1.5 years (as of June 2025), defining more than 300 APIs. The billing team leveraged this experience for their full migration.

Source: freee Developers Hub – TypeSpec Migration (as of June 2026)

---

Background of the Migration — Challenges with 33,000 Lines of OpenAPI YAML

The freee billing team’s internal API definitions had grown to over 33,000 lines of OpenAPI YAML. Direct YAML authoring presented several challenges:

• Redundancy: Repeated schema definitions bloated the files
• Poor readability: Deep nesting made reviews and maintenance difficult
• High maintenance cost: Small changes required edits across many locations

While GraphQL migration was considered, the divergence from existing API structures made it impractical. TypeSpec’s ability to output OpenAPI as an intermediate format was the deciding factor.

---

Migration Decision Points — Comparing Continued OpenAPI vs TypeSpec Adoption

The team compared options:

Aspect	Direct OpenAPI	TypeSpec Adoption
Description volume	Redundant, 33k+ lines	Significantly reduced
Readability	Deep nesting, hard to review	TS-like, easier to read
Lock-in	None	Avoided via OpenAPI output
Tool integration	Existing tools	Enhanced with linter, formatter, generators
Learning curve	Low for YAML users	Medium (lower for TS users)

By always generating OpenAPI, the team retains access to the mature OpenAPI ecosystem. One caveat is the default interpretation of explode (true in OpenAPI, false in TypeSpec), which can be explicitly specified to avoid issues.

Source: freee Developers Hub

---

Actual Migration Steps and Development Flow

The migration followed this flow:

1. Create TypeSpec definition files
2. Apply built-in Linter and Formatter
3. Compile TypeSpec to generate OpenAPI YAML
4. Use ogen (Go) or orval (React) for code generation
5. Review generated code and apply manual adjustments as needed

Leveraging prior experience from the spend management team, the billing team completed the migration smoothly. Existing OpenAPI assets were reused by regenerating from TypeSpec definitions.

---

Effects After Introduction and Remaining Challenges

Post-migration, the team reported that “directly reading or writing OpenAPI is no longer something we consider.” No critical issues have been reported.

The only remaining consideration is the explode default difference, which is easily managed with explicit declarations. TypeSpec has successfully balanced productivity and quality in API definition.

---

freee’s TypeSpec Usage Examples and Recommended Points

Following the spend management team, the billing team has fully adopted TypeSpec. Expansion to other teams is under consideration.

Recommended points: – Especially effective for teams managing large-scale APIs – Improves description quality while preserving the OpenAPI ecosystem – Backed by Microsoft official support and an active community

TypeSpec is emerging as a strong option for schema-driven development.

Source: freee Developers Hub TypeSpec Introduction

Frequently Asked Questions (FAQ)

Q1. How does TypeSpec differ from OpenAPI?

A. TypeSpec uses a more concise, TS-like syntax to describe APIs and automatically generates OpenAPI. OpenAPI serves as the output format for compatibility.

Q2. What is the migration cost?

A. Conversion from existing OpenAPI or manual rewriting is required. In the freee case, leveraging prior team knowledge allowed completion in a relatively short time, even at 33,000-line scale, with no major blockers reported.

Q3. Can existing OpenAPI assets be reused?

A. Yes. By generating OpenAPI from TypeSpec, existing code generators (ogen, orval, etc.) can continue to be used without change.

Q4. Is there a lock-in risk with TypeSpec?

A. Lock-in is avoided by always outputting OpenAPI as an intermediate artifact, allowing continued use of mature OpenAPI tools.

Q5. How does it combine with code generation tools?

A. It pairs excellently with ogen (Go) and orval (TypeScript/React), and when combined with Linter/Formatter, enables a high-quality automated code generation pipeline.

Related articles:

• Sakana Fugu — Multi-agent System as A Model
• AWSに繋げなくてもテストできる？新サービス「AWS Blocks」を触ってみた
• 画面操作を“録画”→AIが作業代行 Codexに新機能「Record & Replay」