Type mapping

The types used in the component's code are mapped to the types of Rib (WebAssembly value encoding or WAVE) and to JSON (when used in the invocation REST API). This page lists all the supported types and how they are mapped.

User types to Rib

This section describes how various types of the used programming language are mapping to types used by the Rib scripting language and the CLI invoke functions. These are WebAssembly component-model types, and their values are described using the WAVE (WebAssembly Value Encoding) (opens in a new tab) format.

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 exampleMethod(
    @languageCodes(['en'])
    unstructuredTextWithLanguageCode: UnstructuredText,
): Promise<void> {
    // ...
}

export type UnstructuredText =
  | {
      tag: 'url';
      val: string;
    }
  | {
      tag: 'inline';
      val: string;
      languageCode?: string;
    };

Unstructured binary

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

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

export type UnstructuredBinary =
  | {
      tag: 'url';
      val: string;
    }
  | {
      tag: 'inline';
      val: Uint8Array;
      mimeType?: string;
    };

Multimodal values

Agents can work with multimodal values as input or output. 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.

@multimodal()
async exampleMethod(
  metadata: MyStructuredData[],
  @languageCodes(['en', 'de'])
  text: UnstructuredText[],
  @mimeTypes('image/jpeg', 'image/png')
  image: UnstructuredBinary[]
): Promise<void> {
  // ...
}

Rib types to JSON

The invocation API uses a special JSON format to describe invocation parameters and results.

When using the REST API, the JSON-encoded values must be extended with a JSON-encoded type information as well. This is described in details in the Invoke via HTTP page.

The following sections define how each WASM type and it's corresponding WAVE value encoding is mapped to Golem's value JSON format.

Primitive types

Tuples

The following WIT type:

tuple<u32, string, char>

is encoded in WAVE as

(1234, "hello world", 'g')

and in JSON as an array of the items:

[1234, "hello world", 103]

Lists

The following WIT type:

list<string>

is encoded in WAVE as

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

and in JSON as an array of the items:

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

Options

The following WIT type:

option<string>

is encoded in WAVE by one of the following:

"implicit some", some("explicit some"), none

In the JSON representation we use null to reprsent none and the inner value if defined:

"implicit some"
null

Results

For the following WIT type:

result<string, string>

The WAVE representation is

"implicit ok", ok("explicit ok"), err("explicit err")

The result type is represented in JSON by an object with either an ok or an err field:

{ "ok": "explicit ok" }
{ "err": "explicit err" }

If the type is unit in the WIT definition, the JSON representation should use null:

result<_, string>

{ "ok": null }

Handles

Handles are identifying resources and returned by invoking resource constructors through the Golem invocation API. Handles are represented as strings in the JSON format and they are not supported by WAVE.

Handles must not be constructed by hand, just forwarded to method invocations as they were returned from the constructors.

Example handle value in JSON representation:

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

Records

Records are a collection of named fields. The JSON representation uses the same names as they appear in the WIT definition:

record {
    a: string,
    b: u32
}

An example WAVE encoding for such a record is:

{ a: "hello", b: 1234 }

The JSON representation is just an object with the same field names:

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

Variants

Variants are encoded in JSON by an object with a single field, where the field's name matches one of the variant's cases:

variant allowed-destinations {
    none,
    any,
    restricted(list<string>),
}

The WAVE encoding for such a variant is

none, any, restricted(["one", "two", "three"])

In JSON the object's single field encodes the case, and the value is null if it has no inner value in the type:

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

Enums

Enums are simply encoded by the case name as a JSON string.

For example:

enum {
    low,
    medium,
    high
}

The WAVE encoding for such an enum is:

low, medium high

and in JSON:

"low"
"medium"
"high"

Flags

Flags represent a set of selected values.

Take the following example WIT type:

flags allowed-methods {
    get,
    post,
    put,
    delete,
}

The WAVE encoding lists zero or more elements of the flags within {}:

{get, put}

The JSON representation is an array of the selected values, each represented by a string:

["get", "put"]