Working with other API specs
Avro Integration
Overview
Taxi can enhance Apache Avro schemas with semantic meaning, enabling:
- Semantic typing for Avro records and fields
- Type-safe data serialization and deserialization
- Integration with Avro-based messaging systems
Semantic Enhancement
While Avro describes data structure and serialization, Taxi adds semantic meaning to enable better data discovery and integration across systems.
Adding Taxi to Avro
Schema Annotation
Add semantic types to Avro using the taxi.dataType attribute:
{
"type": "record",
"namespace": "customer",
"name": "CustomerRecord",
"taxi.dataType": "acme.Customer",
"fields": [
{
"name": "id",
"type": "string",
"taxi.dataType": "acme.CustomerId"
},
{
"name": "email",
"type": "string",
"taxi.dataType": "acme.EmailAddress"
}
]
}
Auto-Type Generation
If no taxi.dataType is specified, Taxi will generate types based on:
- For records: The combination of namespace and name
- For fields: The field name and underlying primitive type
Declaring Avro in Taxi
You can also describe your Avro model directly in Taxi.
Reccomendation: Add taxi types to Avro schemas when possible
You can generate these Avro models by hand - but we don't recommend it.
If you have an Avro schema and can annotate it, it's recommended to annotate that with taxi types, rather than duplicating the schema definition as a Taxi model.
Basic Model Definition
import lang.taxi.formats.AvroMessage
import lang.taxi.formats.AvroField
@AvroMessage
model Customer {
@AvroField(ordinal = 0)
id: CustomerId
@AvroField(ordinal = 1)
email: EmailAddress?
@AvroField(ordinal = 2)
addresses: Address[]
}Field Ordering
Avro serialization depends on field order. Always specify ordinals using @AvroField to ensure consistent serialization.
Type Mapping
Taxi automatically maps Avro types to appropriate semantic types:
@AvroMessage
model Order {
// Maps string to semantic type
@AvroField(ordinal = 0)
orderId: OrderId inherits String
// Maps int to semantic type
@AvroField(ordinal = 1)
quantity: Quantity inherits Int
// Maps array to semantic type array
@AvroField(ordinal = 2)
items: OrderItem[]
}