Type mapping

The types used in the component's code are mapped to JSON when used in the invocation REST API. This page lists all the supported types and how they are mapped.

Language types to JSON

There are some special, Golem agent specific types that can be used in the agent constructor and methods as well:

Unstructured text

Unstructured text is an arbitrary string, optionally annotated with a language code, that is either passed directly to/from the agent, or as an URL reference. The agent can optionally specify the set of supported language codes.

import { UnstructuredText } from '@golemcloud/golem-ts-sdk';
 
async function exampleMethod(
    unstructuredTextWithLanguageCode: UnstructuredText<["en"]>,
): Promise<void> {
    // ...
}

type LanguageCode = string;
 
export type UnstructuredText<LC extends LanguageCode[] = []> =
  | {
      tag: 'url';
      val: string;
    }
  | {
      tag: 'inline';
      val: string;
      languageCode?: LC[number];
    };

Unstructured binary

Unstructured binary data is similar to unstructured text, but it is annotated (and restricted by) MIME types.

import {
  UnstructuredBinary,
} from '@golemcloud/golem-ts-sdk';
 
async exampleMethod(
  unstructuredBinaryWithMimeType: UnstructuredBinary<['application/json']>,
): Promise<void> {
    // ...
}

type MimeType = string;
 
export type UnstructuredBinary<MT extends MimeType[] | MimeType = MimeType> =
  | {
      tag: 'url';
      val: string;
    }
  | {
      tag: 'inline';
      val: Uint8Array;
      mimeType: MT extends MimeType[] ? MT[number] : MimeType;
    };

Multimodal values

Agents can work with multimodal values as input or output. It allows passing an arbitrary number of values of different types in a single parameter or return value. When defining a parameter or return value as multimodal, we define the possible data types that can be used in that position, and the actual values will be an arbitrary number of values of these types, in any combination.

There are three variants of multimodal values supported:

• Multimodal type , allowing to pass an arbitrary number of values which is either an unstructured text or binary.
• MultimodalCustom<T>, allowing to pass an arbitrary number of values which is either an unstructured text or binary or a user defined structured type T.
• MultimodalAdvanced<T> , allowing to pass an arbitrary number of values of the user defined structured type T.

 
type MyStructuredData = {
  field1: string;
  field2: number;
}
 
type TextBinaryOrCustom =
  | { tag: 'text'; val: UnstructuredText }
  | { tag: 'binary'; val: UnstructuredBinary }
  | { tag: 'custom'; val: MyStructuredData }
 
async exampleMultimodalMethod(
  input: Multimodal,
): Promise<void> {
  // ...
}
 
async exampleMultimodalCustomMethod(
  input: MultimodalAdvanced<TextBinaryOrCustom>,
): Promise<void> {
  // ...
}
 
async exampleMultimodalAdvanced(
  input: MultimodalAdvanced<TextOrImage>,
): Promise<void> {
  // ...
}
 
export type TextOrImage =
  | { tag: 'text'; val: string }
  | { tag: 'image'; val: Uint8Array }
 

export type MultimodalAdvanced<T> = T[];
 
export type Multimodal = MultimodalAdvanced<BasicModality>;
 
export type MultimodalCustom<T> = MultimodalAdvanced<CustomModality<T>>;
 
export type BasicModality =
  | { tag: 'text'; val: UnstructuredText }
  | { tag: 'binary'; val: UnstructuredBinary }
 
export type CustomModality<T> =
  | { tag: 'text'; val: UnstructuredText }
  | { tag: 'binary'; val: UnstructuredBinary }
  | { tag: 'custom'; val: T }
 

Composite types in JSON

The REST API encodes structured values using the following JSON shapes:

Records

Records are JSON objects with the same field names as defined in the source code:

{ "a": "hello", "b": 1234 }

Variants

Variants (tagged unions with payloads) are encoded as a single-key JSON object, where the key is the case name. Cases without a payload use null as the value:

{ "restricted": ["one", "two", "three"] }
{ "none": null }
{ "any": null }

Enums

Enums (variants where all cases have no payload) are encoded as a JSON string:

"low"
"medium"
"high"

Options

Optional values are encoded as the inner value when present, or null when absent:

"hello"
null

Results

Result types are encoded as a JSON object with either an ok or an err field:

{ "ok": "success value" }
{ "err": "error message" }

If the success or error type is unit, use null:

{ "ok": null }

Tuples

Tuples are encoded as fixed-order JSON arrays:

[1234, "hello world", 103]

Lists

Lists are encoded as JSON arrays:

["one", "two", "three"]

Maps

Maps are encoded as arrays of key-value pairs (not as JSON objects, to support non-string keys):

[["key1", 100], ["key2", -2]]

Flags

Flags represent a set of selected values, encoded as a JSON array of strings:

["get", "put"]

Handles

Handles identify resources and are returned by invoking resource constructors through the Golem invocation API. They are represented as opaque strings in JSON:

"urn:worker:component-id/worker-name/resource-id"

Handles must not be constructed by hand — use the values returned from resource constructors.