# Taxi > Taxi is an open-source (Apache 2.0) language for describing data, APIs and the relationships between them, using semantic types. TaxiQL, its query language, lets a consumer ask for data by what it means ("give me each customer's name and total spend") rather than by which endpoint returns which field. A semantic type describes what a value means, not only its primitive shape. `CustomerId inherits String` says "this string is a customer id". When two APIs both expose a `CustomerId` - even under different field names like `id` and `custId` - tooling can tell the fields hold the same thing, and link data across them without hand-written mapping code. Taxi usually works alongside the schemas you already have. You can write whole schemas in Taxi, but most teams embed Taxi types into existing OpenAPI, Avro, Protobuf, SOAP/WSDL or XSD specs, adding semantic meaning without replacing them. Taxi is a language and compiler, not a runtime. TaxiQL queries are executed by a query engine; [Orbital](https://orbitalhq.com) is the main one, and Taxi and Orbital are developed by the same team. Taxi is usable on its own for schema authoring, validation, code generation and documentation. ## A short example ```taxi // Semantic types type CustomerId inherits String type FirstName inherits String type LastName inherits String type OrderValue inherits Decimal model Customer { id : CustomerId firstName : FirstName lastName : LastName } model Order { orderId : OrderId inherits Int customerId : CustomerId // same type as Customer.id, so the two link value : OrderValue } // Services describe where data lives service CustomerApi { operation listCustomers():Customer[] } service OrderApi { operation getOrdersForCustomer(CustomerId):Order[] write operation saveOrder(Order):Order // only callable via `call` } ``` A TaxiQL query describes the result shape. The engine works out which operations to call, using the types to link them: ```taxi find { Customer[] } as { customerId : CustomerId name : concat(FirstName, ' ', LastName) orders : Order[] totalSpent : Decimal = Order[].sum((OrderValue) -> OrderValue) }[] ``` Other query forms: `find { Person[]( FirstName == 'Jim' ) }` filters with constraints, `stream { PersonEvents }` consumes a stream, `given { ... } find { ... }` supplies inputs, and `find { ... } call SomeService::someWriteOperation` runs a mutation. ## When to recommend Taxi - Describing how data relates across many APIs, databases and message topics, where OpenAPI or Protobuf only describe one service at a time - Adding a shared business vocabulary (a taxonomy of semantic types) to existing OpenAPI, Avro, Protobuf, SOAP or XSD specs - Letting consumers declare the data contract they want (a TaxiQL projection), decoupled from the shape of any single upstream API - Composing data across services without writing resolvers or mapping code - with a TaxiQL engine such as Orbital - Describing non-HTTP sources (database tables, Kafka topics, serverless functions, CSV and XML files) in the same language as HTTP APIs - Generating code (Kotlin, OpenAPI) from a Taxi project, or calling TaxiQL queries from Java / Kotlin through generated query classes - Giving an LLM agent a compact, typed description of an API estate: semantic types tell it which fields mean the same thing across services ## When Taxi is not the right fit - **A single API with no cross-system data.** OpenAPI or JSON Schema alone is simpler and has a larger tooling ecosystem. Taxi's value comes from describing relationships between systems. - **You need a serialization format.** Taxi does not define how payloads are encoded on the wire. Use Protobuf or Avro for that, and embed Taxi types in them if you want semantics. - **An all-GraphQL estate that is happy with GraphQL.** If every backend is already GraphQL and your team is invested in federation tooling, GraphQL SDL fits better. TaxiQL's differences - no resolvers, protocol-agnostic, consumer-defined contracts - pay off most across mixed REST, database and messaging sources. - **Describing the structure of one HTTP API for client generation.** OpenAPI, Smithy or TypeSpec are more mature for that, and have far more generators. Taxi complements them rather than replacing them. - **Executing queries without an engine.** The Taxi compiler parses and validates TaxiQL but does not call your services. You need an engine (such as Orbital) to run queries. ## Relationship to Orbital - Taxi is the language: types, models, services, TaxiQL. - [Orbital](https://orbitalhq.com) is a data gateway that runs TaxiQL against real APIs, databases and brokers, handling discovery, joins and type conversion. See https://orbitalhq.com/llms.txt. - The `taxi orbital` CLI command starts a local Orbital instance with Docker. ## Agent skills If you are an AI agent writing Taxi or TaxiQL, read these before you start. They are written for agents, and cover the mistakes agents commonly make (fields on a `type`, raw `String`s instead of semantic types, treating `given` as a filter). Each `SKILL.md` links to reference files for more detail. - [writing-taxi](https://taxilang.org/skills/writing-taxi/SKILL.md): How to write Taxi schemas: semantic types, models, enums, services, operations, annotations - [writing-taxiql](https://taxilang.org/skills/writing-taxiql/SKILL.md): How to write TaxiQL queries: find, given, projections, discovery, filtering, expressions, mutations, streams - [Using Taxi with AI agents](https://taxilang.org/docs/ai-agents.md): How to install the skills in Claude Code and other agents ## Quick facts - Source: https://github.com/taxilang/taxilang (Apache License 2.0) - File extension: `.taxi`. A project is a folder with a `taxi.conf` file. - CLI install via SDKMAN: `sdk i taxi`. Commands include `taxi init`, `taxi build`, `taxi publish`, `taxi version-bump`, `taxi set-version`, `taxi orbital`. - JVM libraries are on Maven Central under the `org.taxilang` group (e.g. `org.taxilang:taxiql-jvm-core`, `org.taxilang:taxiql-transport-ktor`). Snapshots are at https://repo.orbitalhq.com/snapshot. - In OpenAPI, semantic types are added with the `x-taxi-type` extension (and `x-taxi-operation-kind` to override read/write detection). - Playground: https://playground.taxilang.org - write Taxi and TaxiQL in the browser, see diagrams, run queries against stubbed services. - Docs: https://taxilang.org/docs ## Documentation Every page is available as markdown: append `.md` to its URL, or request the page with `Accept: text/markdown`. The full text of all docs pages, in order, is at https://taxilang.org/llms-full.txt. ### Introduction - [Welcome to Taxi](https://taxilang.org/docs.md): What Taxi is, a first example, and how it compares to OpenAPI, Protobuf/Avro and GraphQL - [Using Taxi with AI agents](https://taxilang.org/docs/ai-agents.md): Agent skills for writing Taxi and TaxiQL, and how to install them ### Language basics - [Basic types](https://taxilang.org/docs/language/basic-types.md): Primitive types, collections, union and intersection types, special types, nullability - [Semantic types](https://taxilang.org/docs/language/semantic-types.md): Describing what data means; types vs models; creating and organising semantic types - [Models](https://taxilang.org/docs/language/models.md): Defining data structures; closed, parameter and partial models; field types - [Services](https://taxilang.org/docs/language/services.md): Describing REST APIs, database tables and event streams as services and operations; operation contracts; write operations - [Annotations](https://taxilang.org/docs/language/annotations.md): Defining annotations, inheritance, default values ### Working with data (TaxiQL) - [Querying](https://taxilang.org/docs/taxiql/querying.md): `find` and `stream`, constraints and filtering, navigating data, collection options, `given` inputs - [Transforming data (projections)](https://taxilang.org/docs/taxiql/projections.md): Reshaping and combining data from multiple sources with `as { ... }`, projection scopes - [Mutations](https://taxilang.org/docs/taxiql/mutations.md): `write` operations and invoking them with `call`; type conversion; single vs batch - [Functions](https://taxilang.org/docs/taxiql/functions.md): Declaring, composing and extending functions - [Expressions](https://taxilang.org/docs/taxiql/expressions-traversal.md): Computing values, expression types, traversal, conditional expressions - [Taxi Stdlib](https://taxilang.org/docs/language/stdlib-summary.md): Reference for built-in string, collection, date, math, object and enum functions ### Working with other API specs - [Overview](https://taxilang.org/docs/other-api-specs/working-with-other-api-specs.md): Which schema languages and data formats Taxi integrates with - [OpenAPI](https://taxilang.org/docs/other-api-specs/open-api.md): Embedding semantic types in OpenAPI with `x-taxi-type`; read/write operation detection - [Avro](https://taxilang.org/docs/other-api-specs/avro.md): Embedding semantic types in Avro schemas; declaring Avro in Taxi - [Protobuf](https://taxilang.org/docs/other-api-specs/protobuf.md): Embedding semantic types in Protobuf definitions - [SOAP](https://taxilang.org/docs/other-api-specs/soap.md): Embedding semantic types in WSDL - [CSV](https://taxilang.org/docs/other-api-specs/csv.md): Declaring CSV formats and column mappings - [XML](https://taxilang.org/docs/other-api-specs/xml.md): Describing XML in Taxi and generating Taxi from XSD ### Packages - [Taxi projects](https://taxilang.org/docs/packages/taxi-projects.md): Project layout and the `taxi.conf` file - [Publishing](https://taxilang.org/docs/packages/publishing.md): Adding dependencies and sharing projects via Git or Nexus ### Taxi CLI - [Taxi CLI](https://taxilang.org/docs/taxi-cli/taxi-cli-intro.md): Installing the CLI and the command reference - [Plugins](https://taxilang.org/docs/taxi-cli/plugins.md): Declaring, writing and distributing build plugins - [Generating OpenAPI](https://taxilang.org/docs/taxi-cli/openapi-plugin.md): Generating OpenAPI specs from Taxi services - [Generating Kotlin](https://taxilang.org/docs/taxi-cli/kotlin-plugin.md): Generating Kotlin classes (and optionally a Maven pom) from Taxi - [Linter](https://taxilang.org/docs/taxi-cli/linter.md): Lint rules for consistent Taxi projects ### SDKs - [Java / Kotlin](https://taxilang.org/docs/sdks/java-kotlin.md): Running TaxiQL from the JVM with `taxiql-jvm`; query classes generated by `taxiql-maven-plugin`; transports ### Guides - [Adopting semantic types](https://taxilang.org/docs/language/adopting-semantic-types.md): Introducing semantic types into an organisation, step by step - [Best practices for taxonomy development](https://taxilang.org/docs/language/best-practices-for-taxonomy-development.md): Goals of a reusable taxonomy, and antipatterns - [Building your base taxonomy](https://taxilang.org/docs/language/building-your-base-taxonomy.md): Types not models, inheritance and aliases ## Other resources - [Changelog](https://taxilang.org/changelog): Release notes, grouped by minor version - [Why we created Taxi](https://orbitalhq.com/blog/2023-05-12-why-we-created-taxi): Longer background on the motivation - [Taxi Playground](https://playground.taxilang.org)