JSON - WAVE mapping

The invocation API uses a special JSON format to describe invocation parameters and results. As the parameter and result types are defined by the Web Assembly components, the natural way to encode parameter and return values is the WAVE (WebAssembly Value Encoding) (opens in a new tab) format.

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.

When using the CLI tool, it is possible to either use the WAVE format directly, or use this JSON format as described in details in the Invoke via CLI 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"]