openapi: 3.1.0
info:
  title: Taxi Language Conversion Schemas API
  description: Taxi is an open-source language for describing APIs, data models, and how data relates across an entire ecosystem. This API covers the Taxi schema compiler service, TaxiQL query execution, schema registry operations, and tooling integrations for generating Taxi schemas from existing API specifications.
  version: '1.0'
  contact:
    name: Taxi Language
    url: https://taxilang.org/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.taxilang.org
  description: Taxi API service
tags:
- name: Schemas
  description: Taxi schema management and compilation
paths:
  /schemas:
    get:
      operationId: listSchemas
      summary: List Schemas
      description: Returns all registered Taxi schemas in the schema registry.
      tags:
      - Schemas
      parameters:
      - name: namespace
        in: query
        required: false
        description: Filter by namespace
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum results to return
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of schemas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaList'
    post:
      operationId: registerSchema
      summary: Register Schema
      description: Register a new Taxi schema with the schema registry.
      tags:
      - Schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaRegistrationRequest'
      responses:
        '201':
          description: Schema registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        '400':
          $ref: '#/components/responses/BadRequest'
  /schemas/{schema_id}:
    get:
      operationId: getSchema
      summary: Get Schema
      description: Returns a specific Taxi schema by ID.
      tags:
      - Schemas
      parameters:
      - name: schema_id
        in: path
        required: true
        description: Schema identifier
        schema:
          type: string
      responses:
        '200':
          description: Schema details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        '404':
          $ref: '#/components/responses/NotFound'
  /schemas/compile:
    post:
      operationId: compileSchema
      summary: Compile Schema
      description: Compile and validate a Taxi schema, returning parsed types and any errors.
      tags:
      - Schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompileRequest'
      responses:
        '200':
          description: Compilation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompileResult'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    TypeDefinition:
      type: object
      properties:
        qualified_name:
          type: string
          description: Fully qualified type name
        name:
          type: string
          description: Short type name
        namespace:
          type: string
          description: Namespace
        kind:
          type: string
          enum:
          - type
          - model
          - enum
          - type_alias
          description: Type kind
        fields:
          type: array
          items:
            $ref: '#/components/schemas/TypeField'
        annotations:
          type: array
          items:
            type: string
          description: Applied annotations
    ServiceDefinition:
      type: object
      properties:
        name:
          type: string
          description: Service name
        base_url:
          type: string
          description: Service base URL
        operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationDefinition'
        annotations:
          type: array
          items:
            type: string
    CompileResult:
      type: object
      properties:
        success:
          type: boolean
          description: Whether compilation succeeded
        types:
          type: array
          items:
            $ref: '#/components/schemas/TypeDefinition'
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceDefinition'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/CompileError'
    TypeField:
      type: object
      properties:
        name:
          type: string
          description: Field name
        type:
          type: string
          description: Field type (qualified name)
        nullable:
          type: boolean
        annotations:
          type: array
          items:
            type: string
    SchemaRegistrationRequest:
      type: object
      required:
      - name
      - content
      properties:
        name:
          type: string
          description: Schema name
        content:
          type: string
          description: Taxi schema source content
        version:
          type: string
          description: Schema version
    SchemaList:
      type: object
      properties:
        schemas:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        total:
          type: integer
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error description
        errors:
          type: array
          items:
            type: string
          description: List of specific error messages
    Schema:
      type: object
      properties:
        id:
          type: string
          description: Schema registry identifier
        name:
          type: string
          description: Schema name
        namespace:
          type: string
          description: Taxi namespace
        version:
          type: string
          description: Schema version
        content:
          type: string
          description: Raw Taxi schema content
        type_count:
          type: integer
          description: Number of types defined
        service_count:
          type: integer
          description: Number of services defined
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CompileError:
      type: object
      properties:
        message:
          type: string
          description: Error message
        line:
          type: integer
          description: Line number of error
        column:
          type: integer
          description: Column number of error
        severity:
          type: string
          enum:
          - error
          - warning
    CompileRequest:
      type: object
      required:
      - content
      properties:
        content:
          type: string
          description: Taxi schema source to compile
        imported_schemas:
          type: array
          items:
            type: string
          description: Additional schema IDs to import during compilation
    OperationDefinition:
      type: object
      properties:
        name:
          type: string
          description: Operation name
        method:
          type: string
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
        url:
          type: string
          description: Operation URL
        return_type:
          type: string
          description: Return type qualified name
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/OperationParameter'
    OperationParameter:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: Parameter type qualified name
        placement:
          type: string
          enum:
          - path
          - query
          - body
          - header
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: Taxi Language Documentation
  url: https://docs.taxilang.org/