Specification overview
ethdebug/format is currently in the design phase and specification is only just beginning.
Contents
This specification currently contains the following primary schemas:
- ethdebug/format/type
A schema for representing high-level data types such as arrays of integers, payable addresses, etc.
- ethdebug/format/pointer
A schema for representing dynamic data address ranges in the EVM, particularly to indicate where high-level variables are allocated in the machine state.
- ethdebug/format/program
A schema for representing high-level semantics from the perspective of an annotated compiled bytecode.
- ethdebug/format/info
A schema for bundling all debug information for a compilation, including programs, shared types, sources, and compilation metadata.
In addition, this format defines namespaces containing schemas for common concerns:
- ethdebug/format/data
A namespace of schemas containing definitions of commonly used data representations, such as how to represent raw byte strings and unsigned integers.
- ethdebug/format/materials
A namespace of schemas for representing "external" resources, such as compiler source inputs.
For an introduction to the concepts behind these schemas, see the conceptual overview.
These schemas are specified as JSON Schema documents, draft 2020-12.
For the full collection of raw schema listings (in YAML format), please see the
schemas/ directory
in this project's GitHub repository.
A schema:ethdebug/format/<path> id, as seen throughout this
specification, names the schema whose source is
schemas/<path>.schema.yaml in that repository, at whatever version
of the specification is in question. The id is an identifier, not a
web address. Emitted data should not place it
in a $schema key: editors treat $schema as a URL and report an
error. ethdebug/format/info and ethdebug/format/program reject
a $schema key outright, through unevaluatedProperties: false;
ethdebug/format/info/resources stays open to one for now. See
Identification for how objects in this format
name the schema they conform to.
Conventions used by this format
Terminology
This specification uses the term "this format" to refer to the entirety of this project's scope (all formal schemas and any additional informally-described constraints). Sections within this specification use the term "this schema" to refer to whatever schema is related to the section in question.
This specification uses the terms "known" and "unknown" synonymously to mean "within the scope of this format" and "outside the scope of this format", respectively.
RFC-2119
The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this specification are to be interpreted as described in RFC-2119.