Specification
An OpenAPI alternative to describe REST APIs for type-safe code generation.
1. Introduction
This document describes the TypeAPI specification. The TypeAPI specification defines a JSON format to describe REST APIs for type-safe code generation.
1.1 Goals
- Enable the generation of clean, production-ready code.
- Maintain a minimalist and stable core specification.
- Optimize for strictly-typed and object-oriented programming paradigms.
- Facilitate the straightforward implementation of custom code generation engines.
1.2 Non-Goals
- Describe non JSON payloads i.e. XML or form-encoded.
- Describe every possible API structure and JSON payload.
- Providing complex JSON validation capabilities.
1.3 Reasoning & Motivation
The Code Generation Imperative
Modern software architecture relies heavily on cross-language API integration, automated SDK generation, and end-to-end type safety. To achieve reliable code generation across strongly typed languages (e.g., TypeScript, Java, C#, Go, Rust), an API description format must provide unambiguous, deterministic mapping to object-oriented and functional type systems.
Limitations of Existing Standards
Industry-standard specifications such as OpenAPI and JSON Schema were primarily architected for validation and documentation of dynamic JSON payloads rather than strong static type modeling. Consequently, they introduce critical structural challenges for code generators:
- Over-Flexibility & Ambiguity: Constructs like complex dynamic validation keywords, loose pattern properties, and unrestricted anyOf/oneOf/allOf polymorphism often lack direct, idiomatic equivalents in statically typed target languages.
- Non-Deterministic AST Mapping: Generous schema flexibility forces code generators to rely on heuristic assumptions, language-specific vendor extensions (x-*), or fragile custom parser configurations.
- Implementation Fragmentation: Because generators must handle edge cases non-uniformly, generated client SDKs and server stubs across different languages frequently drift in behavior, structural representation, and type guarantees.
The TypeAPI Approach
TypeAPI resolves this friction by establishing a strict, schema-first model explicitly optimized for code generation and cross-language interoperability.
- Type-System Alignment: TypeAPI eliminates schema constructs that cannot be cleanly mapped into native structural or nominal type models, guaranteeing deterministic code synthesis across target runtimes.
- Zero Custom Extensions Required: By standardizing object structures, primitive mappings, and endpoint operational layouts, TypeAPI removes the need for non-standard vendor annotations to achieve type safety.
- Ecosystem Compatibility: TypeAPI maintains structural bridgeability with OpenAPI and JSON Schema, allowing seamless import/export workflows while serving as an uncompromising foundation for automated toolchains.
By framing API definitions through the lens of program language semantics rather than dynamic validation constraints, TypeAPI ensures that client SDKs, server interfaces, and data models remain robust, predictable, and maintainable across their entire life cycle.
1.4 Vision
TypeAPI aims to standardize API integration by shifting the industry towards automated, specification-driven workflows. By providing a rigorous machine-readable definition, TypeAPI eliminates the requirement for manual client SDK development and ensures architectural consistency across disparate systems.
Client-Side Automation
The specification facilitates the automatic generation of stable, type-safe client libraries. This enables seamless integration of external services without the overhead of manual implementation, allowing developers to interact with any TypeAPI-compliant service through a standardized interface.
Server-Side Abstraction
TypeAPI decouples business logic from underlying server technology. The specification enables the generation of server stubs, controllers, and data models for diverse frameworks (e.g., Spring, Symfony), allowing for infrastructure migration or technology swaps with minimal impact on core implementation logic.
Code-First Integrity
TypeAPI prioritizes a code-first approach to prevent specification drift. By deriving the API definition directly from implementation metadata, TypeAPI ensures that documentation remains a live, accurate reflection of the service. This methodology addresses the inherent limitations of design-first approaches by maintaining absolute synchronization between the specification and the deployed API at scale.
1.5 Specification
The complete details of the TypeAPI specification are hosted on TypeHub. You can explore the full interactive documentation and schema definitions at the TypeHub Official Specification.
The source of the specification is developed and maintained on GitHub. You can view the raw JSON definition and contribute to its development at the TypeAPI GitHub Repository.
2. Operations
Every TypeAPI has a Root definition. The Root must contain at least the operations and definitions keyword i.e.:
{
"operations": {
"getMessage": { ... },
},
"definitions": {
"TypeA": { ... },
"TypeB": { ... }
}
}
The operations keyword contains a map containing Operation objects. The key represents the identifier of this operation, through the dot notation i.e. user.getMessage you can group your operations into logical units.
{
"operations": {
"getMessage": {
"description": "Returns a hello world message",
"method": "GET",
"path": "/hello/world",
"return": {
"schema": {
"type": "reference",
"target": "Hello_World"
}
}
}
},
"definitions": {
"Hello_World": {
"type": "struct",
"properties": {
"message": {
"type": "string"
}
}
}
}
}
2.1 Return
Every operation can define a return type. In the above example the operation simply returns a Hello_World object.
2.2 Arguments
Through the arguments keywords you can map values from the HTTP request to specific method arguments. In the following example we have an argument status which maps to a query parameter and an argument payload which contains the request payload.
{
"operations": {
"insertMessage": {
"description": "Inserts and returns a hello world message",
"method": "POST",
"path": "/hello/world",
"arguments": {
"status": {
"in": "query",
"schema": {
"type": "integer"
}
},
"payload": {
"in": "body",
"schema": {
"type": "reference",
"target": "Hello_World"
}
}
},
"return": {
"schema": {
"type": "reference",
"target": "Hello_World"
}
}
}
},
"definitions": {
"Hello_World": {
"type": "struct",
"properties": {
"message": {
"type": "string"
}
}
}
}
}
This would map to the following HTTP request.
POST https://api.acme.com/hello/world?status=2
Content-Type: application/json
{
"message": "Hello"
}
2.3 Throws
Besides the return type an operation can return multiple exceptional states in case an error occurred. Every exceptional state is then mapped to a specific status code i.e. 404 or 500. The generated client SDK will throw a fitting exception containing the JSON payload in case the server returns such an error response code. The client will either return the success response or throw an exception. This greatly simplifies error handling at your client code.
{
"operations": {
"getMessage": {
"description": "Returns a hello world message",
"method": "POST",
"path": "/hello/world",
"return": {
"schema": {
"type": "reference",
"target": "Hello_World"
}
},
"throws": [{
"code": 404,
"schema": {
"type": "reference",
"target": "Error"
}
}, {
"code": 500,
"schema": {
"type": "reference",
"target": "Error"
}
}]
}
},
"definitions": {
"Hello_World": {
"type": "struct",
"properties": {
"message": {
"type": "string"
}
}
},
"Error": {
"type": "struct",
"properties": {
"message": {
"type": "string"
}
}
}
}
}
3. Definitions
The definitions keyword maps to the TypeSchema specification and represents a map containing Struct types. Those types are then used to describe incoming and outgoing JSON payloads.
4. Security
The security keyword describes the authorization mechanism of the API, the following types are supported:
apiKey
Describes an arbitrary HTTP header containing an access token i.e. X-Api-Key which can be specified with the in and name keyword.
httpBasic
Describes an Authorization header using the Basic type. See RFC7617, base64-encoded credentials.
httpBearer
Describes an Authorization header using the Bearer type. See RFC6750, bearer tokens to access OAuth 2.0-protected resources.
oauth2
Describes an OAuth2 endpoint. The client will automatically request an access token using the client_credentials authorization grant on usage. The following keywords can be used: tokenUrl, authorizationUrl and optionally scopes.
{
"security": {
"type": "httpBearer",
},
"operations": {
"getMessage": { ... }
},
"definitions": {
"Hello_World": { ... }
}
}