Base schema
The schema on this page is extended by other, more specific schemas as part of the larger ethdebug/format specification. These other schemas specify the representation of many common kinds of types (e.g. including signed/unsigned integers, arrays, structs, mappings, etc.). In order to adhere to this format fully, compilers that represent known types should do so with the appropriate more-specific schema.
Please see the ethdebug/format/type schema for representing these supported types.
This format defines the ethdebug/format/type/base schema for representing data types from high-level languages. These types may be user-defined or supplied as native data types in a language. This schema affords the representation of complex/parametric types, whose definition composes other types (e.g., arrays and structs, which contain at least one underlying type).
This base schema itself is designed to be extended by other schemas in this format, namely ethdebug/format/type. It serves to specify what is minimally necessary for a type to be a valid representation (i.e., all type representations must adhere to at least this base schema).
Differences from ethdebug/format/type
This base schema defines the structure of a type representation without respect to any known kind of type.
Unconstrained kind
field
As described in key concepts
Types are organized by kind
and
Known vs. unknown kinds,
ethdebug/format/type imposes constraints on type representations' kind
field. This base schema makes no restriction on the value of this field
(other than it must be defined and must be a string).
The primary purpose for the kind
field is to discriminate type objects
into the appropriate corresponding subschema for a well-understood family of type.
Although ethdebug/format/type/base does not impose any constraints on
objects based on the kind
field, it includes this field so as to encourage
the one-to-one pairing between values for this field and corresponding
subschemas.
When extending this schema, there should exist exactly one corresponding
schema for each kind
value.
The class
field is always optional
Although ethdebug/format/type does not require the class
field to be
defined for known types, it does require this field for representations of
unknown types.
The ethdebug/format/type/base schema does not ever require this field.
A complex base type contains
other base types
As described in key concept
Elementary vs. complex types,
this format allows the representation of types whose definition
includes other types. Both the primary schema and this base schema
require type composition to be represented via complex types' contains
field.
These two schemas differ by which type schema this field is
permitted to compose. Naturally, ethdebug/format/type's contains
field
composes ethdebug/format/type representations, and
ethdebug/format/type/base's contains
field composes
ethdebug/format/type/base representations.
As a result of this, ethdebug/format/type/base defines its own type wrapper schema.
Base type wrapper schema
- Explore
- View source
- Playground
- YAML
- JSON
title: '{ "type": ... }'
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:
oneOf:
- $ref: "schema:ethdebug/format/type/base"
- $ref: "schema:ethdebug/format/type/reference"
required:
- type
{
"title": "{ \"type\": ... }",
"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": {
"oneOf": [
{
"$ref": "schema:ethdebug/format/type/base"
},
{
"$ref": "schema:ethdebug/format/type/reference"
}
]
}
},
"required": [
"type"
]
}
Full base schema
- Explore
- View source
- Playground
- YAML
- JSON
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/type/base"
title: ethdebug/format/type/base
description:
Defines the minimally necessary schema for a data type.
Types belong to a particular `class` (`"elementary"` or `"complex"`),
and are further identified by a particular `kind`.
type: object
oneOf:
- $ref: "#/$defs/ElementaryType"
- $ref: "#/$defs/ComplexType"
$defs:
ElementaryType:
title: Base elementary type
description:
Represents an elementary type (one that does not compose other types)
type: object
properties:
class:
type: string
const: elementary
kind:
type: string
contains:
not:
description:
"Elementary types **must not** specify a `contains` field
(to make it easier to discriminate elementary vs. complex)"
required:
- kind
examples:
- kind: uint
bits: 256
ComplexType:
title: Base complex type
description:
Represents a complex type, one that composes other types (e.g., arrays,
structs, mappings)
type: object
properties:
class:
type: string
const: complex
description: Indicates that this is a complex type
kind:
type: string
description: The specific kind of complex type, e.g., array or struct
contains:
title: Complex type `contains` field
description:
Either a type wrapper, an array of type wrappers, or an object
mapping to type wrappers.
oneOf:
- $ref: "#/$defs/TypeWrapper"
- $ref: "#/$defs/TypeWrapperArray"
- $ref: "#/$defs/TypeWrapperObject"
required:
- kind
- contains
examples:
- kind: array
contains:
type:
kind: uint
bits: 256
- kind: struct
contains:
- member: x
type:
kind: uint
bits: 256
- member: y
type:
kind: uint
bits: 256
- kind: mapping
contains:
key:
type:
kind: address
payable: true
value:
type:
kind: uint
bits: 256
TypeWrapper:
title: '{ "type": ... }'
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:
oneOf:
- $ref: "schema:ethdebug/format/type/base"
- $ref: "schema:ethdebug/format/type/reference"
required:
- type
TypeWrapperArray:
title: '{ "type": ... }[]'
description: A list of wrapped types, where the wrapper may add fields
type: array
items:
$ref: "#/$defs/TypeWrapper"
TypeWrapperObject:
title: '{ "key": { "type": ... }, ... }'
description:
A key-value mapping of wrapped types, where the wrapper may add fields
type: object
additionalProperties:
$ref: "#/$defs/TypeWrapper"
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "schema:ethdebug/format/type/base",
"title": "ethdebug/format/type/base",
"description": "Defines the minimally necessary schema for a data type. Types belong to a particular `class` (`\"elementary\"` or `\"complex\"`), and are further identified by a particular `kind`.",
"type": "object",
"oneOf": [
{
"$ref": "#/$defs/ElementaryType"
},
{
"$ref": "#/$defs/ComplexType"
}
],
"$defs": {
"ElementaryType": {
"title": "Base elementary type",
"description": "Represents an elementary type (one that does not compose other types)",
"type": "object",
"properties": {
"class": {
"type": "string",
"const": "elementary"
},
"kind": {
"type": "string"
},
"contains": {
"not": {
"description": "Elementary types **must not** specify a `contains` field (to make it easier to discriminate elementary vs. complex)"
}
}
},
"required": [
"kind"
],
"examples": [
{
"kind": "uint",
"bits": 256
}
]
},
"ComplexType": {
"title": "Base complex type",
"description": "Represents a complex type, one that composes other types (e.g., arrays, structs, mappings)",
"type": "object",
"properties": {
"class": {
"type": "string",
"const": "complex",
"description": "Indicates that this is a complex type"
},
"kind": {
"type": "string",
"description": "The specific kind of complex type, e.g., array or struct"
},
"contains": {
"title": "Complex type `contains` field",
"description": "Either a type wrapper, an array of type wrappers, or an object mapping to type wrappers.",
"oneOf": [
{
"$ref": "#/$defs/TypeWrapper"
},
{
"$ref": "#/$defs/TypeWrapperArray"
},
{
"$ref": "#/$defs/TypeWrapperObject"
}
]
}
},
"required": [
"kind",
"contains"
],
"examples": [
{
"kind": "array",
"contains": {
"type": {
"kind": "uint",
"bits": 256
}
}
},
{
"kind": "struct",
"contains": [
{
"member": "x",
"type": {
"kind": "uint",
"bits": 256
}
},
{
"member": "y",
"type": {
"kind": "uint",
"bits": 256
}
}
]
},
{
"kind": "mapping",
"contains": {
"key": {
"type": {
"kind": "address",
"payable": true
}
},
"value": {
"type": {
"kind": "uint",
"bits": 256
}
}
}
}
]
},
"TypeWrapper": {
"title": "{ \"type\": ... }",
"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": {
"oneOf": [
{
"$ref": "schema:ethdebug/format/type/base"
},
{
"$ref": "schema:ethdebug/format/type/reference"
}
]
}
},
"required": [
"type"
]
},
"TypeWrapperArray": {
"title": "{ \"type\": ... }[]",
"description": "A list of wrapped types, where the wrapper may add fields",
"type": "array",
"items": {
"$ref": "#/$defs/TypeWrapper"
}
},
"TypeWrapperObject": {
"title": "{ \"key\": { \"type\": ... }, ... }",
"description": "A key-value mapping of wrapped types, where the wrapper may add fields",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/TypeWrapper"
}
}
}
}
Example schema extensions for particular types
These examples show valid schemas that extend ethdebug/format/types/base for particular kinds of types.
Note: These are just examples and may not correspond to the canonical ethdebug/format/type schema.
- Example uint type schema
- Example array type schema
- Example mapping type schema
- Explore
- View source
- Playground
- YAML
- JSON
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
class:
type: string
const: elementary
kind:
type: string
const: uint
bits:
type: number
multipleOf: 8
minimum: 8
maximum: 256
required:
- kind
- bits
examples:
- kind: uint
bits: 64
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"class": {
"type": "string",
"const": "elementary"
},
"kind": {
"type": "string",
"const": "uint"
},
"bits": {
"type": "number",
"multipleOf": 8,
"minimum": 8,
"maximum": 256
}
},
"required": [
"kind",
"bits"
],
"examples": [
{
"kind": "uint",
"bits": 64
}
]
}
- Explore
- View source
- Playground
- YAML
- JSON
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
class:
type: string
const: complex
kind:
type: string
const: array
contains:
type: object
properties:
type:
$ref: schema:ethdebug/format/type/base
required:
- type
required:
- kind
- contains
examples:
- kind: array
contains:
type:
kind: string
description: An example schema for array types. See example value for
representing an array of strings (\`string[]\`).
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"class": {
"type": "string",
"const": "complex"
},
"kind": {
"type": "string",
"const": "array"
},
"contains": {
"type": "object",
"properties": {
"type": {
"$ref": "schema:ethdebug/format/type/base"
}
},
"required": [
"type"
]
}
},
"required": [
"kind",
"contains"
],
"examples": [
{
"kind": "array",
"contains": {
"type": {
"kind": "string"
}
}
}
],
"description": "An example schema for array types. See example value for representing an array of strings (\\`string[]\\`)."
}
- Explore
- View source
- Playground
- YAML
- JSON
$schema: https://json-schema.org/draft/2020-12/schema
title: Example mapping type schema
type: object
properties:
class:
type: string
const: complex
kind:
type: string
const: array
contains:
type: object
properties:
key:
type: object
properties:
type:
$ref: schema:ethdebug/format/type/base
required:
- type
value:
type: object
properties:
type:
$ref: schema:ethdebug/format/type/base
required:
- type
required:
- key
- value
required:
- kind
- contains
examples:
- kind: mapping
contains:
key:
type:
kind: address
payable: true
value:
type:
kind: uint
bits: 256
description: An example schema for mapping types. See example value for a
mapping from an \`address payable\` to a \`uint256\`, adhering to this example
schema.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Example mapping type schema",
"type": "object",
"properties": {
"class": {
"type": "string",
"const": "complex"
},
"kind": {
"type": "string",
"const": "array"
},
"contains": {
"type": "object",
"properties": {
"key": {
"type": "object",
"properties": {
"type": {
"$ref": "schema:ethdebug/format/type/base"
}
},
"required": [
"type"
]
},
"value": {
"type": "object",
"properties": {
"type": {
"$ref": "schema:ethdebug/format/type/base"
}
},
"required": [
"type"
]
}
},
"required": [
"key",
"value"
]
}
},
"required": [
"kind",
"contains"
],
"examples": [
{
"kind": "mapping",
"contains": {
"key": {
"type": {
"kind": "address",
"payable": true
}
},
"value": {
"type": {
"kind": "uint",
"bits": 256
}
}
}
}
],
"description": "An example schema for mapping types. See example value for a mapping from an \\`address payable\\` to a \\`uint256\\`, adhering to this example schema."
}