representations.md

Representations of types

Edelweiss data types have canonical representations in the IPLD data model. This document describes the representation of each type and illustrates it via examples based on the DAG-JSON encoding of IPLD values. To learn about the semantics of types, please refer to the User manual for Milestone 1.

For context, note that users of Edelweiss can modify the ultimate representation of types by applying transforms to the canonical representations. Transforms are a feature slated for Milestone 2 of the Edelweiss compiler.

Canonical representations

Bool

Example type definition:

Bool{}

Example value in IPLD DAG-JSON format:

true

Byte

Example type definition:

Byte{}

Example value in IPLD DAG-JSON format:

211

Char

Example type definition:

Char{}

Example value in IPLD DAG-JSON format:

22345

Int

Example type definition:

Int{}

Example value in IPLD DAG-JSON format:

123456789

Float

Example type definition:

Float{}

Example value in IPLD DAG-JSON format:

123.456

String

Example type definition:

String{}

Example value in IPLD DAG-JSON format:

"abc" /* valid UTF8 string */

Bytes

Example type definition:

Bytes{}

Example value in IPLD DAG-JSON format:

{"/": { "bytes": "XXX" /* Base64 encoded binary */ }}

Nothing

Example type definition:

Nothing{}

Example value in IPLD DAG-JSON format:

{}

Link

Example type definition:

Link{ To: Any{} }

Example value in IPLD DAG-JSON format:

{"/": "XXX" /* Base58 encoded CIDv0 or Multibase Base32 encoded CIDv1 */}

List

Example type definition:

List{ Element: Int{} }

Example value in IPLD DAG-JSON format:

[ 1, 2, 3 ]

Map

Example type definition:

Map{ Key: String{}, Value: Int{} }

Example value in IPLD DAG-JSON format:

{ "abc": 123, "def": 456 }

Unfortunately, IPLD encoders generally do not support maps with non-string keys even though the IPLD data model does. To overcome this gap — short of waiting for such support — we plan (for Milestone 2) to represent such maps as IPLD lists of pairs.

Example type definition:

Map{ Key: Float{}, Value: String{} }

Example value in IPLD DAG-JSON format:

[ [ 123.456, "abc" ], [ 456.789, "def" ] ]

Structure

Example type definition:

Structure{
     Fields: Fields{
          Field{Name: "Abc", Value: Int{}},
          Field{Name: "Def", Value: Float{}},
     }
}

Example value in IPLD DAG-JSON format:

{
     "Abc": 123,
     "Def": 456.789,
}

Singleton

Singleton Bool

Example type definition:

SingletonBool{true}

Example value in IPLD DAG-JSON format:

true

Singleton Int

Example type definition:

SingletonInt{123}

Example value in IPLD DAG-JSON format:

123

Singleton Float

Example type definition:

SingletonFloat{123.456}

Example value in IPLD DAG-JSON format:

123.456

Singleton String

Example type definition:

SingletonString{"abc"}

Example value in IPLD DAG-JSON format:

"abc"

Inductive (aka "tagged union")

Example type definition:

Inductive{
     Cases: Cases{
          Case{Name: "C1", Value: Int{}},
          Case{Name: "C2", Value: Float{}},
          Case{Name: "C3", Value: String{}},
     }
}

Example values in IPLD DAG-JSON format:

{ "C1": 123 }

{ "C2": 456.789 }

{ "C3": "abc" }

Union (aka "untagged union")

Example type definition:

Union{
     Cases: Cases{
          Case{Name: "C1", Value: Int{}},
          Case{Name: "C2", Value: Float{}},
          Case{Name: "C3", Value: String{}},
     }
}

Example values in IPLD DAG-JSON format:

123

456.789

"abc"

Service method calls

Example service type definition:

Service{
     Methods: Methods{
          Method{Name: "Method1", Type: Fn{Arg: Int{}, Return: Bool{}}},
          Method{Name: "Method2", Type: Fn{Arg: String{}, Return: Float{}}},
     },
},

Request

Based on the service definition (above), Edelweiss generates a type definition for a method call request. In this case:

Inductive{
     Cases: Cases{
          Case{ Name: "Method1", Value: Int{} }
          Case{ Name: "Method2", Value: String{} }
     },
}

Response

Based on the service definition (above), Edelweiss generates a type definition for a method call response. In this case:

Inductive{
     Cases: Cases{
          Case{ Name: "Method1", Value: Bool{} }
          Case{ Name: "Method2", Value: Float{} }
     },
}