Type mapping

TypeScript

TypeScript agents declare runtime schemas. An arbitrary interface, type alias, or TypeScript union does not define the transport schema. The table uses the Zod adapter as a concrete example. Valibot, ArkType, and Effect adapters have their own supported constructors; do not assume that every schema library feature is supported.

Use s.uint8Array(), s.int8Array(), s.uint16Array(), s.int16Array(), s.uint32Array(), s.int32Array(), s.float32Array(), s.float64Array(), s.bigInt64Array(), and s.bigUint64Array() for typed arrays. All produce lists. The bigint constructors produce decimal-string elements, for example ["-1","0","1"]. s.bytes() aliases the list<u8> constructor, not rich binary.

import { method, s } from "@golemcloud/golem-ts-sdk"
import { z } from "zod"
 
const increment = method({
  input: { count: s.u32(), note: z.optional(z.string()) },
  returns: s.u64(),
})

Effect TypeScript

Effect agents use Schema values. Custom schemas work only when the SDK codec supports their encoded shape; this is not a promise to support arbitrary classes or index signatures.

Tagged unions require a literal _tag. The remaining fields form a record payload: a branch with _tag: "Text" and text: "hi" becomes {"Text":{"text":"hi"}}. A _tag-only branch becomes "Empty". Generic unions use case0, case1, and so on; case names can be configured with WitTypes.withVariantCaseName.

Numeric pins are WitTypes.Int8, Int16, Int32, Int64, Uint8, Uint16, Uint32, Uint64, Float32, and Float64. Typed-array schemas such as WitTypes.Uint8ArraySchema and WitTypes.BigInt64ArraySchema use lists; 64-bit elements remain decimal strings. Schema.NullishOr(T) preserves null and undefined as distinct variant cases rather than collapsing both into one option.

import { Schema } from "effect"
import { method, WitTypes } from "@golemcloud/effect-golem"
 
const increment = method({
  input: { count: WitTypes.Uint32, note: Schema.UndefinedOr(Schema.String) },
  success: WitTypes.Uint64,
})

Rust

Use golem_rust::Schema for custom records and enums. The derive and standard implementations use the shared golem-schema model.

Derives preserve case names by default. Use derive rename / rename_all attributes when a different schema name is needed.

uuid::Uuid and chrono::DateTime<chrono::Utc> have unconditional UUID and datetime implementations; no uuid feature is required. The following optional integrations are enabled on the golem-rust dependency:

The SDK also supports std::time::Duration as duration and std::path::PathBuf as path. It exposes Quantity<U> for quantities, with U implementing QuantityUnit. Derive attributes can select rich text, binary, URL, or path schemas and add restrictions to fields.

Scala

Custom Scala types need a zio.blocks.schema.Schema instance, for example derives Schema.

Case names are preserved. Text(text: String) becomes {"Text":{"text":"hi"}}. Only a single field specifically named value unwraps: Text(value: String) becomes {"Text":"hi"}.

MoonBit

Custom MoonBit records and enums use #derive.golem_schema. Case names are preserved; #derive.case(name=...) can rename a case.

Go

Method parameters are the exported fields of the input struct. Field names become lowerCamelCase, treating each initialism as one word: OrderID → orderId, APIKey → apiKey.

type PaymentMethod interface{ isPaymentMethod() }
type Card struct{ Number string }
type Cash struct{}
func (Card) isPaymentMethod() {}
func (Cash) isPaymentMethod() {}
 
var _ = golem.DefineVariant[PaymentMethod](
    golem.Case[Card]("card"),
    golem.Case[Cash]("cash"),
)
 
type Status int32
const (
    StatusActive Status = iota
    StatusClosed
)
var _ = golem.DefineEnum[Status]("active", "closed")

TypeScript

import { method, s } from "@golemcloud/golem-ts-sdk"
import { z } from "zod"
 
const consume = method({
  input: {
    text: s.unstructuredText({ languages: ["en"] }),
    data: s.unstructuredBinary({ mimeTypes: ["application/octet-stream"] }),
  },
  returns: z.void(),
})

Guest text is {tag:'inline', val:'hi', languageCode:'en'} or {tag:'url', val:'https://example.com/file'}. Guest binary uses val: Uint8Array and optional mimeType. Omit restrictions to accept any language/MIME type.

Effect TypeScript

import { Schema } from "effect"
import { method, Unstructured } from "@golemcloud/effect-golem"
 
const consume = method({
  input: {
    text: Unstructured.UnstructuredText({ restrictions: [{ languageCode: "en" }] }),
    data: Unstructured.UnstructuredBinary({
      restrictions: [{ mimeType: "application/octet-stream" }],
    }),
  },
  success: Schema.Void,
})

Guest values use _tag, not tag: {_tag:"inline", val:"hi", languageCode:"en"} or {_tag:"url", val: url}. Binary inline values carry Uint8Array and optional mimeType. These are boundary-only ElementSpec values, not schemas nestable in Schema.Struct. Optional unstructured values are supported only in the success position.

Rust

use golem_rust::agentic::{UnstructuredText, UnstructuredBinary};
use golem_rust::AllowedLanguages;
 
#[derive(Debug, Clone, AllowedLanguages)]
enum Language {
    #[code("en")]
    English,
}
 
let greeting = UnstructuredText::Text {
    text: "hi".to_string(),
    language_code: Some(Language::English),
};
let data: UnstructuredBinary<String> = UnstructuredBinary::Inline {
    data: vec![1, 2, 3],
    mime_type: "application/octet-stream".to_string(),
};

Use UnstructuredText::Url / UnstructuredBinary::Url for references. Unrestricted text defaults to AnyLanguage, which holds a String; unrestricted binary uses String. Derive AllowedLanguages with #[code(...)] or AllowedMimeTypes with #[mime_type(...)] to restrict values.

Scala

import golem.schema.{UnstructuredText, UnstructuredBinary}
 
val greeting: UnstructuredText["en" | "de"] =
  UnstructuredText.fromInline("hi", "en")
val data: UnstructuredBinary["application/octet-stream"] =
  UnstructuredBinary.fromInline(Array[Byte](1, 2, 3), "application/octet-stream")
val document: UnstructuredText[String] =
  UnstructuredText.fromUrl("https://example.com/file")

Use String for unrestricted language/MIME values, or string-literal unions for restrictions. Both kinds provide fromInline and fromUrl.

MoonBit

let greeting : @schema.UnstructuredText[@schema.AnyLanguage] =
  @schema.UnstructuredText::inline("hi", language="en")
let data : @schema.UnstructuredBinary[@schema.AnyMimeType] =
  @schema.UnstructuredBinary::inline(b"\x01\x02\x03", mime_type="application/octet-stream")
let document : @schema.UnstructuredText[@schema.AnyLanguage] =
  @schema.UnstructuredText::url("https://example.com/file")

The @schema package is golemcloud/golem_sdk/schema. Restriction types implement AllowedLanguages or AllowedMimeTypes; AnyLanguage / AnyMimeType leave them unrestricted. Both kinds provide inline and url constructors.

Go

type English struct{}
func (English) Languages() []string { return []string{"en"} }
 
inline := golem.UnstructuredText[English]{Text: "hi", Language: "en"}
byURL := golem.UnstructuredText[English]{URL: "https://example.com/file"}
data := golem.UnstructuredBinary[golem.AnyMimeType]{
    Data: []byte{1, 2, 3}, MimeType: "application/octet-stream",
}

A non-empty URL selects a reference; otherwise Text or Data holds inline content. Restriction markers implement Languages() []string or MimeTypes() []string. Use golem.AnyLanguage / golem.AnyMimeType for unrestricted values.

TypeScript

import { method, s } from "@golemcloud/golem-ts-sdk"
import { z } from "zod"
 
const analyze = method({
  input: {
    content: s.multimodal([
      { name: "text", schema: s.unstructuredText() },
      { name: "image", schema: s.unstructuredBinary() },
    ]),
  },
  returns: z.void(),
})

Guest arrays use an outer {tag, value} wrapper, for example [{tag:'text', value:{tag:'inline', val:'hi'}}]. Canonical JSON instead uses [{"text":{"inline":{"text":"hi"}}}]. Use runtime schemas to declare custom cases too.

Effect TypeScript

import { Schema } from "effect"
import { method, Multimodal, WitTypes } from "@golemcloud/effect-golem"
 
const analyze = method({
  input: {
    content: Multimodal.multimodal({
      text: Schema.String,
      image: Schema.Array(WitTypes.Uint8),
    }),
  },
  success: Schema.Void,
})

Guest arrays use {_tag: caseName, value}. This example’s canonical JSON is [{"text":"hi"},{"image":[1,2,3]}]. multimodalTextImage() instead uses unstructured content with case names text and image (binary content). multimodalTextImageCustom(schema, {customName:"metadata"}) adds a structured case; its default name is custom. Multimodal carriers are boundary-only, like unstructured elements.

Rust

use golem_rust::agentic::MultimodalAdvanced;
use golem_rust::MultimodalSchema;
 
#[derive(MultimodalSchema)]
enum TextOrImage {
    Text(String),
    Image(Vec<u8>),
}
 
let content = MultimodalAdvanced {
    items: vec![TextOrImage::Text("hi".to_string())],
};

Canonical JSON is [{"Text":"hi"}]. Multimodal provides unstructured Text / Binary cases (names preserved); MultimodalCustom<T> adds a structured Custom case. Use MultimodalAdvanced<T> with a MultimodalSchema enum for an explicit case set.

Scala

The Scala SDK currently has no public multimodal wrappers. Use supported structured schemas instead.

MoonBit

#derive.multimodal
pub(all) enum TextOrImage {
  Text(String)
  Image(Bytes)
}

Use @multimodal.Multimodal[TextOrImage] with an items array of enum values. Canonical JSON is [{"Text":"hi"},{"Image":{"bytes":"AQID"}}]. Define the complete set of cases in the enum; names remain Text and Image.

Go

type TextOrImage interface{ isTextOrImage() }
type Text struct{ Value string }
type Image struct{ Value []byte }
func (Text) isTextOrImage() {}
func (Image) isTextOrImage() {}
 
var _ = golem.DefineVariant[TextOrImage](
    golem.WrappedCase[Text]("text"),
    golem.WrappedCase[Image]("image"),
)
 
content := golem.MultimodalOf[TextOrImage]{Text{Value: "hi"}, Image{Value: []byte{1, 2, 3}}}

Canonical JSON is [{"text":"hi"},{"image":[1,2,3]}]. golem.Multimodal provides unstructured text/binary cases. For custom combinations, register a variant and use golem.MultimodalOf[T]; WrappedCase unwraps the Value field.