Generating Taxi from source

Instantiate Taxi from its original source

Java & Kotlin

You can generate Taxi models and services from Java and Kotlin.

Examples are shown in Kotlin throughout this guide, as it makes for shorter code snippets. However, the same approaches will work for Java too.

@DataType & @Namespace

data class Person(...)  // generates demo.Person

data class Person(...)  // generates demo.Person

@DataType is the main annotation to indicate that a class should have a Taxi schema generated.

Namespaces may be defined either through the @Namespace("foo.bar") annotation, or within a @DataType directly.

If the namespace isn't provided through either approach, the package name is used.

Fields on types are exported. By default, the corresponding primitive type in Taxi is used. However, the output type can be customized by specifying the type in a @DataType annotation on the field, which will result in a Type alias within Taxi being generates.

data class Client(@field:DataType("demo.ClientId") val clientId: String,
        val clientName: String,
        @field:DataType("isic.uk.SIC2008") val sicCode: String


// Generates:
namespace demo {
    type Client {
        clientId : ClientId as String
        clientName : String
        sicCode : isic.uk.SIC2008

namespace isic.uk {
    type alias SIC2008 as String
If you're working in Kotlin, using `typealias` with the `@DataType` annotation is recommended over annotating fields directly, as it leads to more readable & maintainable code.

Support for Kotlin Type Aliases

Type aliases can be directly annotated with the @DataType annotation.

data class Bus(val passengers: Passengers)

typealias Passengers = List<Person>

data class Person(val name: PersonName)

typealias PersonName = String

val taxiDef = TaxiGenerator().forClasses(Bus::class.java).generateAsStrings()

// Generates:
type Bus {
    passengers : Passengers

 type Person {
    name : PersonName

type alias PersonName as String
type alias Passengers as Person[]

Taxi Annotation Processor

Annotations on typealias are not supported out-of-the-box through Kotlin's reflection API. In order to get these to work, we need to use an annotation processor.

Capturing annotations at compile time

Add the following to your Maven build:

            <!-- other executions go here -->

This will generate a class called TypeAliases which will be compiled into your source, containing the annotation metadata.

Using typealias annotations when generating Taxi

To consume the annotations generating Taxi, you need to first register the captured metadata.

Add the annotation processor as a dependency to your project, then register the alias metadata:

If you're consuming models from multiple different libraries, each will have it's own `TypeAliases` class generated. Be sure to register them all.
You must have at least one class that **isn't a type alias** annotated with `@DataType` present in your jar in order for type aliases to be generated.


Constraints are supported via the @Constraint annotation.

data class Money(val amount: BigDecimal, val currency: String)

data class SomeRequest(
        @Constraint("currency = 'USD'")
        val amount: Money)
TaxiGenerator().forClasses(Money::class.java, SomeRequest::class.java).generateAsStrings()

// Generates:
namespace vyne {
     parameter type SomeRequest {
        amount : Money(currency = "USD")
     type Money {
        amount : Decimal
        currency : String

Parameter Type

Parameter types are indicated through the @ParameterType annotation.

Services & Operations

Services and Operations are exposed via the @Service and @Operation annotations respectively.

class MyService {
    fun findPerson(@DataType("taxi.example.PersonId") personId: String): Person {

TaxiGenerator().forClasses(MyService::class.java, Person::class.java).generateAsStrings()

// Generates:
namespace taxi.example {
    type Person {
        personId : PersonId as String
    service PersonService {
        operation findPerson(PersonId) : Person

Operations may customize the generated name of operation parameters through the @Parameter annotation:

fun findPerson(@Parameter(name = "personId") id: String): Person ...

Service constraints & contracts

Constraints on parameters are defined by adding constraints to the @Parameter annotation.

Contracts for operations are defined on the method, using the @ResponseContract annotation.

class MyService {
    @ResponseContract(basedOn = "source",
            constraints = ResponseConstraint("currency = targetCurrency")
    fun convertRates(@Parameter(constraints = Constraint("currency = 'GBP'")) source: Money, @Parameter(name = "targetCurrency") targetCurrency: String): Money {
        TODO("Not a real service")


// Generates
namespace taxi.example

type Money {
    currency : Currency as String
    value : MoneyAmount as Decimal
service MoneyService {
    operation convertRates( Money( currency = "GBP" ),
        targetCurrency : String ) : Money( from source, currency = targetCurrency )

Taxi Generator customisation & extensions

Taxi's generator can be customized, adding additional annotations or modfiying the tree structure before source is output.

The most common scenario here is to provide extensions to modify how services are generated. However, you can inject an entirely separate TypeMapper and ServiceMapper for complete control over the generation process. Take a look at TaxiGenerator to get started.

ServiceMapperExtension and OperationMapperExtension provide the ability to modify the way services are generated, injecting custom metadata (eg., to describe HTTP operations, or how to subscribe to a message bus).

The SpringMVC extensions (discussed below) give a good example of how to leverage this.

Spring MVC Extensions

java2taxi ships with extensions for Spring MVC, to add metadata about how services are discovered and invoked. They add the following features:

  • Support for mapping @GetMapping/@PostMapping etc to an HttpOperation() annotation on the output.
    • All HTTP methods are supported
    • Path variable substitution is supported
  • Support for mapping springs @RequestBody annotation to a corresponding @RequestBody annotation on the generated Taxi source.
  • Support for integration with service discovery from Spring Cloud's DiscoveryClient abstraction
Currently, the SpringMVC extensions are part of java2taxi. However, we expect to move these out to their own library in a future release.

Enable the extensions by configuring the TaxiGenerator as follows:

val taxiGenerator = TaxiGenerator(serviceMapper = DefaultServiceMapper(
    operationExtensions = listOf(SpringMvcHttpOperationExtension()),
    serviceExtensions = listOf(SpringMvcHttpServiceExtension(ServiceDiscoveryAddressProvider("mockService")))

Example usage:

class CreditCostService {
    fun getInterestRate(@PathVariable("clientId") @DataType("vyne.demo.ClientId") clientId: String): BigDecimal = BigDecimal.ONE

    // Back off, REST snobs.  Method names are here for testing.
    fun calculateCreditCosts(@PathVariable("clientId") @DataType("vyne.demo.ClientId") clientId: String, @RequestBody request: CreditCostRequest): CreditCostResponse = CreditCostResponse("TODO")


// Generates:
namespace vyne.demo {

    type alias ClientId as String

     type CreditCostRequest {
        deets : String

     type CreditCostResponse {
        stuff : String

    @ServiceDiscoveryClient(serviceName = "mockService")
    service CreditCostService {
        @HttpOperation(method = "GET" , url = "/costs/interestRates/{vyne.demo.ClientId}")
        operation getInterestRate(  ClientId ) : Decimal
        @HttpOperation(method = "POST" , url = "/costs/{vyne.demo.ClientId}/doCalculate")
        operation calculateCreditCosts(  ClientId, @RequestBody CreditCostRequest ) : CreditCostResponse

The tests give the best example of usage.

Maven / Gradle

The binaries are available on Bintray. Be sure to add the repository:


Then grab the artifacts:

<!-- To generate Taxi, you need java2taxi -->

<!-- To annotate your models, you need the annotations package -->

Swagger / OpenApi

It's possible to convert a swagger document to Taxi, using the TaxiGenerator from the openApi package.

This is especially useful if you want to take advantage of Taxi's type extensions, to mix in annotations. (eg., persistence or validation).

Grab the taxi generator from maven:


Then run the converter as follows:

(Note, this example loads source from this reference example from the OpenApi project -

// The actual swagger source is omitted for brevity
val source = IOUtils.toString(URI.create("https://gitlab.com/taxi-lang/taxi-lang/raw/master/swagger2taxi/src/test/resources/openApiSpec/v2.0/yaml/petstore-simple.yaml"))
TaxiGenerator().generateAsStrings(source, "vyne.openApi")

// generated: 
namespace vyne.openApi  {

    type NewPet {
        name : String
        tag : String

     type Pet inherits NewPet {
        id : Int

     type ErrorModel {
        code : Int
        message : String

    service PetsService {
        @HttpOperation(method = "GET" , url = "http://petstore.swagger.io/api/pets")
        operation findPets(  tags : String,  limit : Int ) : Pet[]
        @HttpOperation(method = "POST" , url = "http://petstore.swagger.io/api/pets")
        operation addPet( @RequestBody pet : NewPet ) : Pet
    service PetsIdService {
        @HttpOperation(method = "GET" , url = "http://petstore.swagger.io/api/pets/{id}")
        operation findPetById(  id : Int ) : Pet
        @HttpOperation(method = "DELETE" , url = "http://petstore.swagger.io/api/pets/{id}")
        operation deletePet(  id : Int )
Edit on GitLab