Component JSON

Booleans

Booleans (bool) are serialized as JSON booleans.

• false ↔ false
• true ↔ true

Integers

Integers (u8, u16, u32, u64, s8, s16, s32, s64) may be serialized as either JSON numbers or JSON strings (base-10).

For the best language interoperability, numbers greater than (2⁵³ – 1) or less than -(2⁵³ - 1) should be serialized as base-10 strings.

• 12345 ↔ 12345
• -9007199254740993 ↔ "-9007199254740993"

Floats

Floats (float32, float64) are serialized as JSON numbers, except for infinities and NaN which are serialized as strings (see below).

• 3.1415 ↔ 3.1415
• -11000 ↔ -1.1e4
• NaN ↔ "NaN"
• +∞ ↔ "Infinity"
• -∞ ↔ "-Infinity"

Characters

A character (char) is serialized as a JSON string containing a single Unicode Scalar Value.

• 0x78 ↔ "x"
• 0x4E00 ↔ "\u4e00"
• 0xFE0E ↔ "☃︎"

Strings

A string (string) is serialized as a JSON string representing a sequence of Unicode Scalar Values.

• hello ↔ "hello"
• x×y ↔ "x\u00d7y"

Records

Records (record) are serialized as JSON objects, with field names as object keys. A field of type option may be omitted if its value is none.

• WIT:
  ​​record r {
  ​​  field-1: u8,
  ​​  opt: option<u8>,
  ​​}
  

• JSON:
  ​​{"field-1": 123}
  

Tuples

Tuples (tuple<...>) are serialized as JSON arrays:

• WIT: tuple<string, u8>
• JSON: ["str", 123]

Flags

Flags (flags) are serialized as JSON arrays of strings, where the strings are the flag names:

• WIT:
  ​​flags permissions {
  ​​  read,
  ​​  write,
  ​​  delete,
  ​​}
  

• JSON: ["read", "write"]

Lists

Lists (list<T>) are serialized as JSON arrays.

• WIT: list<u8>
• JSON: [1, 2, 3]

Variants

Variants (variant) are serialized as JSON objects with a single entry. The key of the entry is the variant case name. The value of the entry is the case payload or null if the case has no payload.

• WIT:
  ​​variant filter {
  ​​  all,
  ​​  none,
  ​​  some(list<string>),
  ​​}
  

• JSON:
  • {"all": null}
  • {"some": ["a"]}

Enums

Enums (enum) are serialized as JSON strings with the case name.

• WIT:
  ​​enum directions {
  ​​  north,
  ​​  east,
  ​​  south,
  ​​  west,
  ​​}
  

• JSON: "south"

Options

An option's (option<T>) serialization depends on its contained type T:

• The "none" case is always serialized as JSON null.
• The "some" case is serialized in one of two ways:
  • If T is itself an option<...>, it is serialized as a JSON object {"value": T}
  • Otherwise, it is serialized as just T

This complexity permits a ideomatic encoding of options in most cases while supporting the (presumably) uncommon option<option<...>> pattern.

• WIT: option<option<u8>>
• JSON:
  • Outer option is "none": null
  • Inner option is "none": {"value": null}
  • Both options are "some": {"value": 123}

Results

Results (result<T, E>) are serialized as JSON objects.

• The "ok" case is serialized as {"result": T}
• The "err" case is serialized as {"error": E}

If the T or E type is omitted, the corresponding value will be null.

• WIT: result<u8>
• JSON:
  • {"result": 123}
  • {"error": null}

Resources

Resource handle (resource ID, borrow<T>) serialization is implementation-defined and may generally use any JSON value.

Generic implementations should treat serialized resource handles as opaque data.