Taxi projects & configuration

Layout of a taxi project, and configuring it's build

Taxi projects and files

A Taxi project contains a taxi.conf file, and a collection of files saved with a .taxi. extension.

A typical project might look like this:

├── src/
│   └── sample.taxi
├── tests/
│   └── hello-world/
│       ├── hello-world.spec.json
│       ├── input.csv
│       └── expected-output.json
└── taxi.conf

Taxi files are simple text files, saved with a .taxi extension.

The taxi.conf file

A taxi.conf file describes a project's layout, and the plugins to be invoked after compilation. It follows the HOCON format, which is like supercharged JSON.

name: taxi/maven-sample
version: 0.3.0
sourceRoot: src/
plugins: {
   taxi/kotlin: {
      maven: {
         groupId: "lang.taxi"
         artifactId: "parent"
         repositories: [
               id: "internal-repo"
               url: "https://newcorp.nexus.com"
               snapshots: true

The source for the config can be seen here, which provides the complete documentation of how projects can be configured.

nameThe name of the taxi project. By convention, follows a format of organisation/project-name
versionThe version of the taxi project
sourceRootThe root location of taxi files to be compiled
outputThe folder where any generated artifacts will be written
pluginsA list of
to be enabled on the project
pluginSettingsDefines where plugins are fetched and loaded from
dependenciesA list of other taxi project dependencies that this project depends on
repositoriesA list of taxi repositories to fetch content from
publishToRepositoryDefines where this project should be published to, should other projects wish to depend on it
credentialsA list of credentials for authenticating with remote repositories


Projects may declare dependencies on other taxi projects. This provides a powerful mechanism for creating modular, re-usable taxonomies across organisations.

The format for declaring dependencies is:

dependencies: {
    org/ProjectName : 0.2.0

An example configuration for declaring dependencies is shown here.

For details on sharing, publishing and depending on taxonomies, see

Distributing taxi projects

Transitive dependencies (ie., depending on projects that depend on other projects) are not yet supported, but are on the roadmap. If this feature is important to you, get in touch on our slack channel.


Repositories define where to try to download dependencies from (and where to publish to). Currently, only Sonatype Nexus is supported, and an experimental Taxi repository -

- is also under development.

The Taxi CLI tries to download each dependency from the list of repositories until successful.

The format for declaring a repository in your taxi.conf file is as follows:

repositories: [
      // The name of the repository.  Optional, but used to reference credentials
      name: "my-corporate-nexus",
      url: "http://localhost:8081",
      // Optional.  Defines the type of repository being used.  Currently only 'nexus' is supported,
      // so this can be omitted.
      type : "nexus",

      // Settings specific to the repository provider.
      // Below settings shown are applicable to a nexus repository
      settings: {
         // The name of the repository as defined within nexus
         repositoryName : taxi

For more information on publishing and sharing taxonomies, see



Credentials define how to authenticate with a repository.

The repositoryName attribute must match the name attribute of a defined repository.

credentials: [
   { repositoryName: "nexus", username: "jimmy", password: "pass123" }

Note - credentials don't need to be defined in your projects main taxi.conf - in fact, we recommend you don't. Instead, define a configuration file at ~/.taxi.conf (your home directory) which contains the credentials. See below for more detail on merging configuration files.

Linter config

Per-project linting rules can be specified in the taxi.conf, to disable or alter the severity of individual linter rules.

The format of the section is as follows:

linter: {
    // The name of the linter rule.
   no-duplicate-types-on-models: {
      // Severity - optional - can be INFO | WARN | ERROR.
      // Defaults to WARN
      // Note that setting to ERROR will cause builds to fail if the rule is violated
      severity: INFO

      // enabled - optional - defaults to true
      enabled: true
   no-primitive-types-on-models: {enabled: false}

Note that the entire linter section is optional. If omitted, all rules are enabled, with the severity defined by each rule. (By convention, this is WARN).

When making changes in VSCode, remember that you must save the `taxi.conf` file before changes are applied.

Merging multiple configuration files

By default, Taxi tooling will merge configuration files from the following locations:

  • The root of the project - ./taxi.conf
  • The home directory - ~/.taxi/taxi.conf

This allows for storing of sensitive information - such as credentials - outside of main projects, and source control.

Edit on Github