cast

README

cast

A simple, opinionated codegen tool for Go APIs. Define your request/response models once in YAML and generate idiomatic Go structs with built-in validation.

Overview

cast takes a YAML definition file and emits plain Go structs with Validate() methods. No reflection, no runtime validator dependencies, and no struct tag magic, just generated Go code.

For TypeScript types, point tygo at the generated output.

Installation

go install codeberg.org/its-astro/cast@latest

Usage

cast generate api.yaml

This will emit a .go file containing your models, request/response types, and validation methods.

Definition Format

models:
  Error:
    message:
      type: string
      required: true

  Session:
    id:
      type: string
      required: true

    token:
      type: string
      required: true
      min_length: 32

    expires_at:
      type: string
      required: true

  User:
    id:
      type: string
      required: true

    username:
      type: string
      required: true
      min_length: 3
      max_length: 32
      pattern: "^[a-zA-Z0-9_]+$"

    email:
      type: string
      required: true
      email: true

    website:
      type: string
      url: true

routes:
  Login:
    request:
      body:
        email:
          type: string
          required: true
          email: true

        password:
          type: string
          required: true
          min_length: 8

    response:
      success:
        session:
          type: Session

        user:
          type: User

      error:
        error:
          type: Error

  GetUser:
    request:
      query:
        id:
          type: string
          required: true

    response:
      success:
        user:
          type: User

      error:
        error:
          type: Error

Generated Output

cast generates standalone exported request/response types and models:

type LoginRequestBody struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

func (m *LoginRequest) Validate() error

Supported Types

• string
• number
• bool
• array
• model references

For more information on types and field syntax, see the wiki.

Supported Validations

Validation	Types
required	all
min_length	string
max_length	string
min_items	array
max_items	array
min	number
max	number
email	string
url	string
pattern	string

For anything not covered, use pattern with a regex.

TypeScript Types

cast emits plain Go structs, so any Go→TypeScript tool will work. tygo is recommended:

tygo generate

Limitations

• Circular references are not supported
• No WebSocket support

License

cast is licensed under the Clear BSD License.