Key concepts
The ethdebug/format/type schema includes definitions for a few concepts that are worth highlighting here.
Types are organized by kind
{
"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 class
es: 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
- Single type
- Ordered list of types
- Object mapping of types by key
This is an example array type, which composes exactly one other type.
{
"kind": "array",
"contains": {
"type": {
"kind": "uint",
"bits": 256
}
}
}
This is an example array type, which composes an ordered list of member types.
{
"kind": "struct",
"contains": [{
"name": "balance",
"type": {
"kind": "uint",
"bits": 256
}
}, {
"name": "scoreSheet",
"type": {
"id": "<some opaque ID for some `ScoreSheet` type>"
}
}]
}
In this example, please note how this struct type represents member names
with a "name"
field alongside the "type"
field, and note how the
value of "type"
can be either a complete representation or a reference
object in the form of { id }
.
This is an example mapping type, which composes an object mapping of types by key.
{
"kind": "mapping",
"contains": {
"key": {
"type": {
"kind": "address"
}
},
"value": {
"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
- Explore
- View source
- Playground
- YAML
- JSON
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/type/wrapper"
title: ethdebug/format/type/wrapper
description:
A wrapper around a type. Defines a `"type"` field that may include a full
Type representation or a reference to a known Type by ID. Note that this
schema permits additional properties on the same object.
type: object
properties:
type:
# Discriminate between reference and type based on presence of `id`
if:
required:
- id
then:
$ref: "schema:ethdebug/format/type/reference"
else:
$ref: "schema:ethdebug/format/type"
required:
- type
examples:
- name: beneficiary
type:
kind: address
payable: true
- type:
id: "<opaque-id>"
$defs:
Array:
title: '{ "type": ... }[]'
description: A list of wrapped types, where the wrapper may add fields
type: array
items:
$ref: "schema:ethdebug/format/type/wrapper"
Object:
title: '{ "key": { "type": ... }, ... }'
description:
A key-value mapping of wrapped types, where the wrapper may add fields
type: object
additionalProperties:
$ref: "schema:ethdebug/format/type/wrapper"
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "schema:ethdebug/format/type/wrapper",
"title": "ethdebug/format/type/wrapper",
"description": "A wrapper around a type. Defines a `\"type\"` field that may include a full Type representation or a reference to a known Type by ID. Note that this schema permits additional properties on the same object.",
"type": "object",
"properties": {
"type": {
"if": {
"required": [
"id"
]
},
"then": {
"$ref": "schema:ethdebug/format/type/reference"
},
"else": {
"$ref": "schema:ethdebug/format/type"
}
}
},
"required": [
"type"
],
"examples": [
{
"name": "beneficiary",
"type": {
"kind": "address",
"payable": true
}
},
{
"type": {
"id": "<opaque-id>"
}
}
],
"$defs": {
"Array": {
"title": "{ \"type\": ... }[]",
"description": "A list of wrapped types, where the wrapper may add fields",
"type": "array",
"items": {
"$ref": "schema:ethdebug/format/type/wrapper"
}
},
"Object": {
"title": "{ \"key\": { \"type\": ... }, ... }",
"description": "A key-value mapping of wrapped types, where the wrapper may add fields",
"type": "object",
"additionalProperties": {
"$ref": "schema:ethdebug/format/type/wrapper"
}
}
}
}
Type reference schema
A type reference is an object containing the single "id"
field. This field
must be a string or a number.
- Explore
- View source
- Playground
- YAML
- JSON
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/type/reference"
title: ethdebug/format/type/reference
description: A reference to a known type by ID
type: object
properties:
id:
type:
- string
- number
additionalProperties: false
required:
- id
examples:
- id: 5
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "schema:ethdebug/format/type/reference",
"title": "ethdebug/format/type/reference",
"description": "A reference to a known type by ID",
"type": "object",
"properties": {
"id": {
"type": [
"string",
"number"
]
}
},
"additionalProperties": false,
"required": [
"id"
],
"examples": [
{
"id": 5
}
]
}
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.
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
- Explore
- View source
- Playground
- YAML
- JSON
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/type/definition"
title: ethdebug/format/type/definition
description: |
Object containing name and location information for a type.
This schema does not require any particular field, but it **must** contain
at least one property.
type: object
properties:
name:
type: string
location:
$ref: "schema:ethdebug/format/materials/source-range"
anyOf:
- title: Required `name`
required: [name]
- title: Required `location`
required: [location]
examples:
- name: Ballot
location:
source:
id: 5
range:
offset: 10
length: 56
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "schema:ethdebug/format/type/definition",
"title": "ethdebug/format/type/definition",
"description": "Object containing name and location information for a type.\n\nThis schema does not require any particular field, but it **must** contain\nat least one property.\n",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"location": {
"$ref": "schema:ethdebug/format/materials/source-range"
}
},
"anyOf": [
{
"title": "Required `name`",
"required": [
"name"
]
},
{
"title": "Required `location`",
"required": [
"location"
]
}
],
"examples": [
{
"name": "Ballot",
"location": {
"source": {
"id": 5
},
"range": {
"offset": 10,
"length": 56
}
}
}
]
}