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(),
})

The SDK and generated TypeScript bridges, external and guest, use these types:

The SDK exports Datetime from @golemcloud/golem-ts-sdk. External bridges get the same type and the same helpers from @golemcloud/golem-ts-bridge:

• Datetime.parse(text) accepts RFC 3339 with any offset and converts the value to UTC.
• Datetime.toISOString(value) emits UTC RFC 3339 with a Z suffix and up to nine fraction digits.
• Datetime.fromDate(date) and Datetime.toDate(value) convert from and to a JavaScript Date. toDate drops the precision below a millisecond.

parse and toISOString reject a year outside 0000..9999. An external bridge sends a datetime as text, so a datetime outside that range is an encode error.

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.

Generated Rust bridges, external and guest, use these types:

With the serde feature of an external bridge, a datetime serializes as UTC RFC 3339 with a Z suffix and up to nine fraction digits. Deserialization accepts any RFC 3339 offset and converts the value to UTC.

Two bridge types differ from the SDK types on purpose:

• A path value is a path in the agent’s file system, not in the caller’s. A caller-side PathBuf invites local file-system calls on the wrong machine, and a String cannot fail to encode.
• A map value is a list of key-value pairs. Vec<(K, V)> keeps the pairs as they arrive, order included, works for every key type, and lets the caller collect into the map type it wants.

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"}.

A case class with a java.net.URI field needs the Schema[URI] instance in scope for Schema.derived: import golem.schema.Implicits.golemUriSchema. Method parameters and return values of type URI need no import.

golem.schema.Text(text, language) is bare text with an optional language code. Its schema has no restrictions.

The unit marker U of a quantity declares its units with @quantityUnit from golem.runtime.annotations. Every listed unit is allowed and the first is the base unit, so @quantityUnit("m", "cm", "km") sealed trait Length accepts m, cm and km. A single unit, such as @quantityUnit("kg"), is the base unit with no suffixes. The named suffixes argument sets the allowed units exactly: @quantityUnit("m", suffixes = Seq("cm", "km")) accepts only cm and km. A marker without the annotation does not compile.

Generated Scala bridges, external and guest, use these types:

An external bridge has its own copy of GolemPath in golem.bridge.runtime. The time argument of scheduleAt is a java.time.Instant in both modes.

An external bridge sends a datetime as UTC RFC 3339 text with a Z suffix and up to nine fraction digits. It accepts any RFC 3339 offset on input and converts the value to UTC. SchemaValueCodec.formatDatetime and SchemaValueCodec.parseDatetime in golem.bridge.runtime apply the same rules.

MoonBit

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

@schema.Datetime holds seconds since the Unix epoch and nanoseconds, with a UTC year in 0000..9999. Datetime::parse accepts RFC 3339 with any offset and converts the value to UTC. to_string prints UTC with a Z suffix and up to nine fraction digits.

Generated MoonBit bridges, external and guest, use these types. The external runtime has copies of the SDK types, under @runtime instead of @schema:

Fixed-size lists are supported in generated bridges only. A MoonBit agent uses Array[T], which publishes a list schema, because MoonBit types cannot carry the length.

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.