Candid Specification

A name is given either in the syntax of a typical programming language identifier, or as an arbitrary string in quotes:

Identifiers cannot be keywords of the Candid grammar. In case a name is needed that coincides with a keyword, it has to be quoted as a text string.

A function type describes the list of parameters and results and their respective types. It can optionally be annotated to be query, which indicates that it does not modify any state and can potentially be executed more efficiently (e.g., on cached state). (Other annotations may be added in the future.)

We identify <funcann> lists in a function type up to reordering.

The list of parameters must be shorter than 2^32 values; the same restriction apply to the result list. The result list of a oneway function must be empty.

As a ``shorthand'', the types of parameters and results in a function type may be prefixed by a name:

The chosen names only serve documentation purposes and have no semantic significance. However, duplicate names are not allowed.

All three types are equivalent.

The content of message arguments and results is data. Three basic forms of data types can be distinguished: primitive data, which are basic values, and constructed data, which are compound forms of data types, and references, which point to a resource in the network.

Primitive types describe the possible forms of primitive data.

The type nat describes a natural number (unsigned integer) of unlimited range. There are also variants limited to 8, 16, 32, or 64 bit value range with fixed-size representations.

Note: Values of type nat have variable length representations in the binary serialisation format, and hence take up space proportional to (the logarithm of) their value. As long as typical values are small, they may hence be more space-efficient than the fixed size types.

The type int describes an integer number (signed) of unlimited range. There are also variants limited to 8, 16, 32, or 64 bit value range with fixed-size representations.

Note: Values of type nat have variable length representations in the binary serialisation format, and hence take up space proportional to (the logarithm of) their value. As long as typical values are small, they may hence be more space-efficient than the fixed size types.

Floating-point values are represented in IEEE 754 binary format and are supported in single precision (32 bit) and double precision (64 bit).

Boolean truth values are represented by the type bool.

Text strings are represented by the type text and consist of a sequence of Unicode scalar values.

Note: The text type is distinguished from vec nat8 (a UTF-8 string) or vec nat32 (a sequence of code points) in order to allow bindings to map it to a suitable string type, and enable the binary format to select an efficient internal representation independently.

The type null has exactly one value (the null value) and therefore carries no information. It can e.g. be used as a placeholder for optional fields that ought to be added to a record in future upgrades, or for variant cases that do not need any value, see below.

The type reserved is a type with unknown content that ought to be ignored. Its purpose is to occupy field ids in records in order to prevent backwards/forwards compatibility problems, see the description of record types below.

Note: This type has a similar role as reserved fields in proto buffers.

The type empty is the type of values that are not present. Its purpose is to mark variants that are not actually there, or – as argument types of function reference – indicate that they will not be called.

Constructed types describe compound or aggregated forms of values.

An option is a value of a specific data type that may be absent.

A vector is a homogeneous sequence of values of the same data type.

A shorthand exists for the specific vector blob, which is an arbitrary sequence of bytes:

A record is a heterogeneous sequence of values of different data types. Each value is tagged by a field id which is a numeric value that has to be unique within the record and carries a single value of specified data type. The order in which fields are specified is immaterial.

We identify <fieldtype> lists in a record type up to reordering.

The id is described as a simple unsigned integer that has to fit the 32 bit value range. It can be given in either decimal or hexadecimal notation:

An id value must be smaller than 2^32 and no id may occur twice in the same record type.

An id can also be given as a name, which is a shorthand for a numeric id that is the hash of that name:

The purpose of identifying fields by unique (numeric or textual) ids is to support safe upgrading of the record type returned by a function: a new version of a function can safely add fields to an old record as long as their id has not been used before. See the discussion on upgrading below for more details.

The hash function is specified as

This expansion implies that a hash collision between field names within a single record is disallowed.

This hash function has the the following useful properties:

The hash function does not have the property that every numeric value can be turned into a human-readable preimage. Host languages that cannot support numeric field names will have to come up with a suitable encoding textual encoding of numeric field names, as well as of field names that are not valid in the host language.

Field ids can also be omitted entirely, which is just a shorthand for picking either 0 (for the first field) or N+1 when the previous field has id N.

The latter two records are equivalent.

A variant is a tagged union of different possible data types. The tag is given by a numeric id that uniquely determines the variant case. Each case is described as a field. The order in which fields are specified is immaterial.

We identify <fieldtype> lists in a variant type up to reordering.

A field id must be smaller than 2^32 and no id may occur twice in the same variant type.

Like for record fields, the id for a variant tag can also be given as a name, which is a shorthand for its hash.

The type of a variant field can be omitted, in which case it is null.

This abbreviation only applies to variants. At the same time, variants do not allow the tuple field abbreviation for omitting the field id.

A third form of value are references. They represent first-class handles to (possibly remote) functions, services, or principals.

An actor reference points to a service and is described by an actor type. Through this, services can communicate connections to other services.

A function reference is described by its function type. For example, they allow passing callbacks to other functions.

A principal reference points to an identity, such as a canister or a user. Through this, we can authenticate or authorize other services or users.

Types can be named via type definitions.

Type definitions are mutually recursive, i.e., they can refer to themselves or each other. However, every type cycle must be productive, that is, go through a type expression that is not just an identifier. A type definition that is vacuous—only equal to itself—is not allowed.

In order to allow splitting interface definitions up into multiple files or share common definitions between multiple interfaces, import declarations are provided.

An import refers to another interface file by URL. The semantics is that of textual inclusion, except that definitions from the imported file must not refer to definitions from the importing file.

File A.dfn:

File B.dfn:

Open Question: Instead of a flat name space, should we require qualified names for imports?

An interface description consists of a sequence of imports and type definitions, possibly followed by a service declaration. A service declaration names and specifies a service actor by specifying an actor type. The actor type may also be given by referring to the name of a type definition for an actor reference type.

The optional name given to the service in an interface description is immaterial; it only serves as documentation.

Most primitive types cannot be changed in an upgrade.

An exception are integers, which can be specialised to natural numbers:

Additional rules apply to empty and reserved, which makes these a bottom resp. top type:

An option or vector type can be specialised via its constituent type.

Furthermore, an option type can be specialised to either null or to its constituent type:

The premise means that the rule does not apply when the constituent type is itself null, an option or reserved. That restriction is necessary so that there is no ambiguity. For example, otherwise there would be two ways to interpret null when going from opt nat to opt opt nat, either as null or as ?null.

Q: The negated nature of this premise isn’t really compatible with parametric polymorphism. Is that a problem? We could always introduce a supertype of all non-nullable types and rephrase it with that.

In a specialised record type, the type of a record field can be specialised, or a field can be added.

NOTE: There is a need for a mechanism to also remove fields (which means adding a field when a record appears as an argument). The precise mechanism is still work in progress.

For a specialised variant, the type of a tag can be specialised, or a tag can be removed.

For a specialised function, any parameter type can be generalised and any result type specialised. Moreover, arguments can be dropped while results can be added. That is, the rules mirror those of tuple-like records in that they are ordered and can only be extended at the end.

where NI* is the <nat> sequence 1..|<datatypeNI>*|, respectively.

Viewed as sets, the annotations on the functions must be equal.

For a service, a method can be specialised (by specialising its function type), or a method added. Essentially, they are treated like records of functions.

To define the actual coercion function, we extend the subtyping relation to a ternary elaboration relation T <: T' ~> f, where f is a suitable coercion function of type T -> T'.

This section describes how abstract Candid values of the types described by Candid are serialised into a binary representation for transfer between services.

Serialisation is defined by three functions T, M, and R given below.

Most Candid values are self-explanatory, except for references. There are two forms of Candid values for service references and principal references:

Likewise, there are two forms of Candid values for function references:

T and M create a byte sequence described below in terms of natural storage types (i<N> for N = 8, 16, 32, 64, f<N> for N = 32, 64). The bytes are sequenced according to increasing significance (least significant byte first, also known as little-endian).

The following notation is used:

T maps an Candid type to a byte sequence representing that type. Each type constructor is encoded as a negative opcode; positive numbers index auxiliary type definitions that define more complex types. We assume that the fields in a record or variant type are sorted by increasing id and the methods in a service are sorted by name.

Every nested type is encoded as either a primitive type or an index into a list of type definitions. This allows for recursive types and sharing of types occurring multiple times:

Type definitions themselves are represented as a list of serialised data types:

The data types in this list can themselves refer to each other (or themselves) via I.

Note:

M maps an Candid value to a byte sequence representing that value. The definition is indexed by type. We assume that the fields in a record value are sorted by increasing id.

R maps an Candid value to the sequence of references contained in that value. The definition is indexed by type. We assume that the fields in a record value are sorted by increasing id.

Note:

Deserialisation is the parallel application of the inverse functions of T, M, and R defined above, with the following mechanism for robustness towards future extensions:

These measures allow the serialisation format to be extended with new types in the future, as long as their representation and the representation of the corresponding values include a length prefix matching the above scheme, and thereby allowing an older deserialiser not understanding them to skip over them. The subtyping rules ensure that upgradability is maintained in this situation, i.e., an old deserialiser has no need to understand the encoded data.

A defines the argument mapping. Essentially, an argument list is serialised into the triple (T,M,R) as if it was a single closed record. T and M are combined into a single byte stream B, where they are preceded by the string ``DIDL'' as a magic number and a possible list of type definitions. We assume that the argument values are sorted by increasing id.

The vector T*(<datatype>*) contains an arbitrary sequence of type definitions (see above), to be referenced in the serialisation of the other <datatype> vector.

The same representation is used for function results.

Note:

Analoguous to types, a few syntactic shorthands are supported that can be reduced to the basic value forms: