Base schema

warning

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
  • Unconstrained kind field
  • The class field is always optional
  • A complex base type contains other base types
• Full base schema
• Example schema extensions for particular types

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).

Note to implementers

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

Loading ....

View source

YAML

ethdebug/format/type/base#/$defs/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

JSON

ethdebug/format/type/base#/$defs/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"
  ]
}

Playground

Loading...

Full base schema

Explore

Loading ....

View source

YAML

ethdebug/format/type/base

$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"

JSON

ethdebug/format/type/base

{
  "$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"
      }
    }
  }
}

Playground

Loading...

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

Explore

Loading ....

View source

YAML

schema.yaml

$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

JSON

schema.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
    }
  ]
}

Playground

Loading...

Example array type schema

Explore

Loading ....

View source

YAML

schema.yaml

$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[]\`).

JSON

schema.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[]\\`)."
}

Playground

Loading...

Example mapping type schema

Explore

Loading ....

View source

YAML

schema.yaml

$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.

JSON

schema.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."
}

Playground

Loading...