⚠️ IMPORTANT: 常见错误提醒

• 命令名是 tot_spec (下划线), 不是 tot-spec (连字符)
• -o 参数必须是文件夹路径, 不是文件名
• 禁止手动修改 codegen 生成的代码, 使用 Field Attributes 调整

tot-spec

Generate type-safe data structures and RPC service interfaces from YAML specifications. Ensures consistency across Rust, Python, TypeScript, Java, and Swift codebases.

Installation

cargo install --locked --force tot_spec_cli
# or from local
cargo install --locked --force --path .

Quick Start

# Generate code for a specific language
tot_spec -i <spec_folder> -c <generator> -o <output_FOLDER>

# Available generators: rs_serde, java_jackson, swift_codable, py_dataclass, typescript, swagger

Spec File Structure

meta:
  rs_serde:
    package: my_crate
  java_jackson:
    package: com.example.myapp

models:
  - name: User
    type:
      name: struct
      fields:
        - name: id
          type: string
          required: true
        - name: age
          type: i32

methods:
  - name: GetUser
    desc: "Get user by ID"
    request: GetUserRequest
    response: GetUserResponse

Model Types

Struct

Standard data structure with fields.

models:
  - name: CreateUserRequest
    type:
      name: struct
      fields:
        - name: username
          type: string
          required: true
        - name: email
          type: string

Enum

Tagged union/sum type with variants.

models:
  - name: PaymentMethod
    type:
      name: enum
      variants:
        - name: CreditCard
          payload_type: string
        - name: PayPal

New Type

Wrapper type for domain modeling.

models:
  - name: UserId
    type:
      name: new_type
      inner_type: string
    attributes:
      rs_extra_derive: Hash, PartialEq

Virtual

Shared fields mapped to traits/interfaces.

models:
  - name: BaseRequest
    type:
      name: virtual
      fields:
        - name: request_id
          type: string

  - name: CreateUserRequest
    type:
      name: struct
      extend: BaseRequest
      fields:
        - name: username
          type: string

Const

Enum-like constant definitions.

models:
  - name: StatusCode
    type:
      name: const
      value_type: i32
      values:
        - name: Ok
          value: 0
        - name: Error
          value: 1

Supported Types

Primitives: bool, i8, i16, i32, i64, f64, string, bytes

Special: decimal, bigint, json

Containers: list[T], map[string] (key is always string)

References: TypeName or namespace.TypeName

RPC Methods

Define service methods with typed requests and responses.

methods:
  - name: CreateUser
    desc: "Create a new user account"
    request: CreateUserRequest
    response: CreateUserResponse

Field Attributes

⚠️ NEVER manually edit generated code! Use attributes in the spec to customize codegen output.

Language-specific customization via attributes:

models:
  - name: MyModel
    type:
      name: struct
      fields:
        - name: custom_map
          type: map[string]
          attributes:
            rs_type: std::collections::BTreeMap<String, String>
            rs_extra_derive: Hash, PartialEq

Rust Attributes

Python Attributes

Other Languages

Similar attributes exist for Java (java_*), Swift (swift_*), TypeScript (ts_*).

Includes

Compose specs with namespace prefixes.

includes:
  - path: common_types.yaml
    namespace: common

models:
  - name: MyModel
    type:
      name: struct
      fields:
        - name: data
          type: common.DataModel

Language Examples

See examples/ for generated code in each language.

Rust (rs_serde): serde structs with #[derive(Serialize, Deserialize)]

Python (py_dataclass): @dataclass with to_dict/from_dict

TypeScript: interface definitions

Swift (swift_codable): Codable structs

Java (java_jackson): Jackson POJOs

Resources

references/

• examples.md – Generated code samples for each language with usage examples
• patterns.md – Common patterns: pagination, error handling, CRUD operations
• rpc.md – RPC service definitions with JSON-RPC models

scripts/

• validate_spec.py – Validate YAML spec syntax before generation
• update_fixtures.sh – Update test fixtures for CI/CD