Working with other API specs
OpenAPI Integration
Overview
Taxi can be embedded within OpenAPI specifications to add semantic meaning to APIs. This allows you to:
- Define semantic types for request/response models
- Add semantic meaning to API parameters
- Create a unified semantic layer across multiple APIs
Semantic Enhancement
Adding Taxi to OpenAPI
Basic Syntax
Taxi metadata is added using x-taxi-type extensions in your OpenAPI spec:
x-taxi-type:
name: com.acme.MyType # The semantic type name
create: false # Optional flag to control type creationType Creation Behavior
The create flag controls whether new types are created if they don’t exist.
The default behaviour varies between models and field attributes - and defaults to the reccomended best practice for each.
| Context | Default | Behavior |
|---|---|---|
| Response Models | true | Creates new types if not found |
| Field Attributes | false | Requires types to exist |
Type Creation
Semantic types let you share data between systems, while avoiding tight coupling. Try to use existing types (where the semantics match), or create new types in a shared taxonomy - rather than creating types in your OpenAPI spec
Only create new types (create: true) when you're intentionally extending your semantic model, or creating a type you're not ready to share yet.
Enriching OpenAPI Components
Response Models
Add semantic meaning to response types:
components:
schemas:
Customer:
x-taxi-type:
name: acme.Customer
properties:
id:
type: string
x-taxi-type:
name: acme.CustomerId
email:
type: string
x-taxi-type:
name: acme.EmailAddress
Input Parameters
Enrich API parameters with semantic types:
paths:
/customers/{id}:
get:
parameters:
- name: id
in: path
schema:
type: string
x-taxi-type:
name: acme.CustomerId
Field Attributes
Add semantic meaning to model fields:
components:
schemas:
Customer:
properties:
name:
type: string
x-taxi-type:
name: acme.CustomerName
# Only create if type doesn't exist
create: true
Best Practices
- Type Management
# Good - References existing semantic type
x-taxi-type:
name: acme.CustomerName
create: false
# Bad - Creates duplicate types
x-taxi-type:
name: acme.CustomerName
create: true # Unnecessary if type exists- Namespace Organization
# Good - Clear namespace hierarchy
x-taxi-type:
name: com.acme.customer.CustomerName
# Bad - Flat namespace
x-taxi-type:
name: CustomerName- Type Reuse
# Good - Reuses common types
components:
schemas:
Customer:
properties:
email:
x-taxi-type:
name: common.EmailAddress
# Bad - Creates new types unnecessarily
components:
schemas:
Customer:
properties:
email:
x-taxi-type:
name: acme.customer.CustomerEmail
create: true