Skip to main content

Key concepts

The ethdebug/format/type schema includes definitions for a few concepts that are worth highlighting here.

Types are organized by kind​

Example: Boolean type
{
  "kind": "bool"
}

An ethdebug/format/type type representation is a JSON object with a kind field containing a string value.

kind is a required field for all type representations and is used to discriminate type objects into the appropriate corresponding subschema for a well-understood family of type.

Known vs. unknown kinds​

ethdebug/format/type defines specific subschemas for known kinds of types. Known types correspond 1-to-1 with a reserved constant string value for the kind field.

Type representations should adhere to the specific corresponding subschema when representing a known type. Type representations must not use any of the reserved values for kind for any purpose other than adhering to the corresponding subschema.

This schema makes no restriction on values for the kind field other than these reservations. For custom variations on known types and to represent kinds of types not supported by this format, type representations may use other values for kind that correspond to associated external subschemas.

Note that this format defines a base type schema (ethdebug/format/type/base), to which all representations of unknown (and known) types must conform. For unknown types, ethdebug/format/type places additional constraints in addition to what the base schema specifies.

Elementary vs. complex types​

Type representations in this schema fall into one of two classes: either "elementary" or "complex". Type representations express this disinction in two ways (the optional "class" field, and the absence or existence of a "contains" field).

  • Elementary types do not compose any other types. For example, uint256 is an elementary type. string may be an elementary type for languages that whose semantics treat strings differently than simply an array of characters (like Solidity does).

  • Complex types compose at least one other type. For instance, uint256[] is an array type that composes an elementary type. Complex types in this schema are polymorphic in how they represent this composition; see below for information about complex types' "contains" field.

Complex types' "contains" field​

Complex types inherently compose at least one other type and may do so in one of three forms:

  • Complex types may compose exactly one other type
  • Complex types may compose an ordered list of other types
  • Complex types may compose an object mapping of specific other types by key

All three forms of composition polymorphically use the "contains" field.

As described in Type wrappers and type references below, complex types compose other types by way of wrapper objects of the form { "type": ... }, which possibly includes other fields alongside "type".

Example complex types to show different forms

This is an example array type, which composes exactly one other type.

{
  "kind": "array",
  "contains": {
    "type": {
      "kind": "uint",
      "bits": 256
    }
  }
}

Type wrappers and type references​

This schema defines the concept of a type wrapper and the related concept of a type reference.

Type wrappers serve to encapsulate a type representation alongside other fields in the same object, and to facilitate discriminating which polymorphic form is used for a particular complex type.

Type wrappers are any object of the form { "type": <type>, ...otherProperties }, where <type> is either a complete type representation or a reference to another type by ID.

Example type wrapper with complete type representation
{
  "name": "beneficiary",
  "type": {
    "kind": "address"
  }
}
Example type wrapper with reference by ID
{
  "type": {
    "id": "<opaque-id>"
  }
}

Note that ethdebug/format/type places no restriction on IDs other than that they must be either a number or a string. Other components of this format at-large may impose restrictions, however.

Type wrapper schema​

Loading ....

Type reference schema​

A type reference is an object containing the single "id" field. This field must be a string or a number.

Loading ....

Sometimes types are defined in code​

Languages provide certain kinds of types by way of allowing their definition in user (or runtime) code. These include struct, enum, and alias types.

Types with definition information may include a definition field that specifies the name of the type (its identifier) and/or the source location of its definition.

note

When extending the base type schema for custom kinds of types with definitions, these custom schemas must require the specification of such definitions by way of this same definition field and its associated schema.

This format does not prohibit the inclusion of this definition field for any type, so as to support languages where array types, etc. may be defined by name directly. It is recommended, however, that compilers implementing this format should prefer to use alias type for the common case of assigning a name to a type expression.

Type definition schema​

Loading ....