diff --git a/packages/web/spec/materials/_category_.json b/packages/web/spec/materials/_category_.json
new file mode 100644
index 00000000..3c917bfa
--- /dev/null
+++ b/packages/web/spec/materials/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "ethdebug/format/materials",
+ "position": 5,
+ "link": {
+ "type": "generated-index",
+ "description": "Work-in-progress formal schema for ethdebug format"
+ }
+}
diff --git a/packages/web/spec/materials/compilation.mdx b/packages/web/spec/materials/compilation.mdx
new file mode 100644
index 00000000..a597d03a
--- /dev/null
+++ b/packages/web/spec/materials/compilation.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Compilation schema
+
+
diff --git a/packages/web/spec/materials/id.mdx b/packages/web/spec/materials/id.mdx
new file mode 100644
index 00000000..9a7afd5b
--- /dev/null
+++ b/packages/web/spec/materials/id.mdx
@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Identifiers and references
+
+## Identifier schema
+
+This format defines a very loosely specified schema for external IDs.
+
+
+
+## Reference schema
+
+This format defines a schema for referencing external resources by ID.
+
+
diff --git a/packages/web/spec/materials/overview.mdx b/packages/web/spec/materials/overview.mdx
new file mode 100644
index 00000000..ff017eb4
--- /dev/null
+++ b/packages/web/spec/materials/overview.mdx
@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+:::tip
+
+**ethdebug/format/materials** is a namespace for schemas about external
+resources, including schemas for representing full compiler invocation details,
+schemas for individual sources, particular source ranges, and so on.
+
+Schemas in this namespace exist so that the rest of **ethdebug/format** has
+a consistent way of representing these external resources. These schemas also
+serve to define something of a data model: one aggregation aggregates multiple
+sources, e.g.
+
+:::
+
+This format defines a namespace of schemas for representing external resources
+relevant to smart contract debugging.
+
+## Reading these schemas
+
+The **ethdebug/format/materials** namespace is not a schema itself, but rather
+a collection of closely-related schemas.
+
+These schemas (like all schemas in this format) are specified as
+[JSON Schema](https://json-schema.org), draft 2020-12.
+
+Please refer to the following resources in this section, or see the navigation
+bar for complete contents.
+
+- [Identifiers and references](/spec/materials/id)
+- [Compilation schema](/spec/materials/compilation)
+- [Source schema](/spec/materials/source)
+- [Source range schema](/spec/materials/source-range)
diff --git a/packages/web/spec/materials/source-range.mdx b/packages/web/spec/materials/source-range.mdx
new file mode 100644
index 00000000..e7128d2b
--- /dev/null
+++ b/packages/web/spec/materials/source-range.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Source range schema
+
+
diff --git a/packages/web/spec/materials/source.mdx b/packages/web/spec/materials/source.mdx
new file mode 100644
index 00000000..fcea7942
--- /dev/null
+++ b/packages/web/spec/materials/source.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Source schema
+
+
diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts
index 0216b3fc..4beee819 100644
--- a/packages/web/src/schemas.ts
+++ b/packages/web/src/schemas.ts
@@ -150,4 +150,24 @@ export const schemaIndex: SchemaIndex = {
title: "Region reference",
href: "/spec/pointer/expression#region-references"
},
+
+ "schema:ethdebug/format/materials/id": {
+ title: "Identifier schema",
+ href: "/spec/materials/id#identifier-schema"
+ },
+
+ "schema:ethdebug/format/materials/reference": {
+ title: "Identifier schema",
+ href: "/spec/materials/id#reference-schema"
+ },
+
+ "schema:ethdebug/format/materials/compilation": {
+ title: "Compilation schema",
+ href: "/spec/materials/compilation"
+ },
+
+ "schema:ethdebug/format/materials/source": {
+ title: "Source schema",
+ href: "/spec/materials/source"
+ },
};
diff --git a/schemas/materials/compilation.schema.yaml b/schemas/materials/compilation.schema.yaml
new file mode 100644
index 00000000..d685d83e
--- /dev/null
+++ b/schemas/materials/compilation.schema.yaml
@@ -0,0 +1,86 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/compilation"
+
+title: ethdebug/format/materials/compilation
+description: |
+ An object representing a single invocation of a compiler.
+
+type: object
+properties:
+ id:
+ description: |
+ Compilation ID. Optional, but **should** be specified.
+
+ This value **should** be globally-unique and generated only from the
+ compiler inputs (settings, sources, etc.); the same compiler inputs/
+ settings **should** produce the same identifier.
+
+ $ref: "schema:ethdebug/format/materials/id"
+
+ compiler:
+ type: object
+ title: Compiler name and version
+ properties:
+ name:
+ type: string
+ description: Compiler name
+
+ version:
+ type: string
+ description: |
+ Compiler version.
+
+ This value **should** be specified using the most detailed version
+ representation available, i.e., including source control hash and
+ compiler build information whenever possible.
+
+ required:
+ - name
+ - version
+
+ examples:
+ - name: lllc
+ version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++
+
+ settings:
+ description: |
+ Compiler settings in a format native to the compiler.
+
+ For compilers whose settings includes full source representations, this
+ field **should** be specified in such a way that avoids large data
+ redundancies (e.g. if compiler settings contain full source
+ representations, then this field would significantly duplicate the
+ information represented by the `sources` field in this object).
+
+ In situations where settings information duplicates information
+ represented elsewhere in **ethdebug/format**, compilers **may** adopt
+ any reasonable strategy, e.g.:
+ - omit duplications partially (leaving the rest of the settings
+ intact)
+ - omit this field entirely
+ - specify this field as a hash of the full settings
+ representation (with the expectation that users of this format will
+ have access to the full representation by some other means)
+
+ allOf:
+ - true
+
+ sources:
+ type: array
+ items:
+ $ref: "schema:ethdebug/format/materials/source"
+
+required:
+ - compiler
+ - sources
+
+examples:
+ - compiler:
+ name: lllc
+ version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++
+ sources:
+ - id: 0
+ path: stdin
+ contents: |
+ (add 1 (mul 2 (add 3 4)))
+ language: LLL
diff --git a/schemas/materials/id.schema.yaml b/schemas/materials/id.schema.yaml
new file mode 100644
index 00000000..98468e97
--- /dev/null
+++ b/schemas/materials/id.schema.yaml
@@ -0,0 +1,13 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/id"
+
+title: ethdebug/format/materials/id
+description: An opaque external ID (likely generated by compiler)
+
+type:
+ - number
+ - string
+
+examples:
+ - 5
+ - "five"
diff --git a/schemas/materials/reference.schema.yaml b/schemas/materials/reference.schema.yaml
new file mode 100644
index 00000000..0c1eccb3
--- /dev/null
+++ b/schemas/materials/reference.schema.yaml
@@ -0,0 +1,22 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/reference"
+
+title: ethdebug/format/materials/reference
+description: A reference to an external resource by ID
+
+type: object
+properties:
+ id:
+ $ref: "schema:ethdebug/format/materials/id"
+
+ type:
+ enum:
+ - compilation
+ - source
+
+required: [id]
+
+unevaluatedProperties: false
+
+examples:
+ - id: 1
diff --git a/schemas/materials/source-range.schema.yaml b/schemas/materials/source-range.schema.yaml
new file mode 100644
index 00000000..bccf805c
--- /dev/null
+++ b/schemas/materials/source-range.schema.yaml
@@ -0,0 +1,56 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/source-range"
+
+title: ethdebug/format/materials/source-range
+description: |
+ A range of bytes in a particular source.
+
+ Note that this refers to the bytes range in the original character encoding
+ for the source, not the character encoding used for strings in this JSON
+ format (UTF-8). For compilers that support input sources in encodings other
+ than this format's transmission encoding, compilers **must** address source
+ ranges in this original encoding, and debuggers **must** re-encode source
+ contents obtained from this format _before_ performing any range addressing.
+
+ (Compilers that only accept UTF-8 or ASCII are naturally exempt from this
+ concern.)
+
+type: object
+properties:
+ compilation:
+ title: Compilation reference by ID
+ $ref: "schema:ethdebug/format/materials/reference"
+
+ source:
+ title: Source reference by ID
+ $ref: "schema:ethdebug/format/materials/reference"
+
+ range:
+ type: object
+ properties:
+ offset:
+ description: Byte offset at beginning of range
+ type: number
+
+ length:
+ description: Number of bytes contained in range
+ type: number
+
+ unevaluatedProperties: false
+
+ required:
+ - offset
+ - length
+
+unevaluatedProperties: false
+
+required:
+ - source
+ - range
+
+examples:
+ - source:
+ id: 5
+ range:
+ offset: 20
+ length: 100
diff --git a/schemas/materials/source.schema.yaml b/schemas/materials/source.schema.yaml
new file mode 100644
index 00000000..c00a276c
--- /dev/null
+++ b/schemas/materials/source.schema.yaml
@@ -0,0 +1,99 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/materials/source"
+
+title: ethdebug/format/materials/source
+description: |
+ An object representing one unit of compiler input, the raw text contents and
+ identifying metadata (such as file path) that were given to the compiler as
+ part of a compilation.
+
+type: object
+properties:
+ id:
+ description: |
+ Source identifier. This field **must** be unique for all sources
+ within a single compiler invocation (compilation).
+ $ref: "schema:ethdebug/format/materials/id"
+
+ path:
+ type: string
+ description: |
+ Hierarchical file-system-like path to this source. This value may
+ be an absolute path, a path relative to some root directory, a path
+ to some resource within a package, etc.
+
+ This value does not need to correspond to any file on disk (either
+ physical or virtual), and might instead refer to a path identifier
+ for a source that was generated by a compiler or other development tool.
+
+ This format makes no specific restrictions on how paths should be
+ specified (e.g., no restriction on path separators, etc.), other than
+ that values for this field should match what users observe elsewhere for
+ the inputs/outputs of this particular compiler invocation.
+
+ If no path information is available for a particular source, e.g. if the
+ source was provided to the compiler via shell standard input, this field
+ should indicate that somehow (e.g., specifying `"path": "stdin"` or
+ similar).
+
+ This field's value **should** be unique across all sources within the
+ same compilation.
+
+ contents:
+ description: |
+ The full contents of the source, possibly re-encoded as UTF-8 to
+ match parent JSON encoding.
+
+ In cases where input source used a different encoding, this object
+ **must** also specify an `encoding` property to indicate the
+ encoding originally used. Where relevant, debuggers **must** also
+ convert these `contents` back to the specified original encoding so
+ as to match code author expectations.
+
+ type: string
+
+ encoding:
+ description: |
+ Character encoding of original source `contents`. This property
+ is **required** if this encoding does not match the JSON transmission
+ encoding (UTF-8), since the value of the `contents` property will
+ represent the text of the source of this JSON encoding.
+
+ This property **must not** appear in objects that do not specify
+ a `contents` property.
+
+ type: string
+
+ language:
+ description: |
+ The high-level language that the source contents are written in.
+
+ type: string
+
+required:
+ - id
+ - path
+ - contents
+ - language
+
+examples:
+ - id: 5
+ path: ./contracts/SimpleStorage.sol
+ contents: |
+ // SPDX-License-Identifier: GPL-3.0
+ pragma solidity >=0.4.16 <0.9.0;
+
+ contract SimpleStorage {
+ uint storedData;
+
+ function set(uint x) public {
+ storedData = x;
+ }
+
+ function get() public view returns (uint) {
+ return storedData;
+ }
+ }
+
+ language:
+ Solidity
diff --git a/schemas/type/definition.schema.yaml b/schemas/type/definition.schema.yaml
index a4974bf6..05e38de2 100644
--- a/schemas/type/definition.schema.yaml
+++ b/schemas/type/definition.schema.yaml
@@ -13,33 +13,20 @@ properties:
name:
type: string
- source:
- type: object
- properties:
- id:
- type:
- - string
- - number
- range:
- type: object
- properties:
- offset:
- type: number
- length:
- type: number
+ location:
+ $ref: "schema:ethdebug/format/materials/source-range"
anyOf:
- title: Required `name`
- required:
- - name
- - title: Required `source`
- required:
- - source
+ required: [name]
+ - title: Required `location`
+ required: [location]
examples:
- name: Ballot
- source:
- id: 5
+ location:
+ source:
+ id: 5
range:
offset: 10
length: 56