[wip]

packages/web/sidebars.ts

@@ -12,7 +12,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
+  docsSidebar: [
+    {type: 'autogenerated', dirName: '.'},
+  ],
 
   // But you can create a sidebar manually
   /*

packages/web/spec/info/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/info",
+  "position": 7,
+  "link": null
+}

packages/web/spec/info/info.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 2
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/info" }}
+  />

packages/web/spec/info/overview.mdx

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Overview
+
+:::tip[Summary]
+
+Objects in the **ethdebug/format/info** schema organize debugging data
+associated with a particular compilation. This includes lookup tables of
+types and pointers by their unique name identifiers, as well as optionally may
+include additional information such as complete program listings and compiled
+source contents.
+
+:::
+
+This schema serves as a root schema, in that it (a) aggregates
+all other schemas in this format (either directly or indirectly), and (b) in
+that no other schema aggregates it.
+
+This schema serves as a suitable target for
+[JSON Schema bundling](https://json-schema.org/understanding-json-schema/structuring#bundling),
+e.g., for implementations that want to reduce complexity around validating
+**ethdebug/format** records and don't want to handle reference resolution
+across schema YAML files.
+
+:::warning
+
+**Note**, however, that "root schema" does not imply "objects in the schema
+always contain all relevant debugging data". Due to widespread practice among
+EVM language compilers to produce their own structured JSON output, objects in
+this schema are not necessarily complete records of debug information.
+
+Compilers may choose to divide **distinct portions of debugging data** into
+**distinct sections of compiler JSON output**. For instance, it likely makes
+sense for a compiler to produce debugging data about a particular contract's
+bytecode alongside that contract bytecode's other output information.
+
+At least until tooling accommodates this concern, debugging implementers
+**must** be aware that they will likely need to aggregate debugging data from
+multiple sections of each supported compiler's own output format.
+
+:::
+
+**However**, this schema _is suitable_ for representing a complete and
+standalone debugging data record for a particular compilation, but
+note the optionality of fields such as `compilation` and `programs`.
+Implementations looking to produce such self-contained debugging data objects
+should study the structure of these (and any other optional fields) and ensure
+that such fields are fully populated.

packages/web/spec/bytecode/_category_.json → packages/web/spec/program/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "ethdebug/format/bytecode",
+  "label": "ethdebug/format/program",
   "position": 5,
   "link": {
     "type": "generated-index",

packages/web/spec/program/context/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Program contexts",
+  "position": 6,
+  "link": null
+}

packages/web/spec/context/code.mdx → packages/web/spec/program/context/code.mdx

@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Code contexts
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context/code" }}
+  schema={{ id: "schema:ethdebug/format/program/context/code" }}
   />

packages/web/spec/bytecode/bytecode.mdx → packages/web/spec/program/context/context.mdx

@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/bytecode" }}
+  schema={{ id: "schema:ethdebug/format/program/context" }}
   />

packages/web/spec/context/variables.mdx → packages/web/spec/program/context/variables.mdx

@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Variables contexts
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context/variables" }}
+  schema={{ id: "schema:ethdebug/format/program/context/variables" }}
   />

packages/web/spec/bytecode/instruction.mdx → packages/web/spec/program/instruction.mdx

@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Instruction schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/bytecode/instruction" }}
+  schema={{ id: "schema:ethdebug/format/program/instruction" }}
   />

packages/web/spec/context/context.mdx → packages/web/spec/program/program.mdx

@@ -7,5 +7,5 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 # Schema
 
 <SchemaViewer
-  schema={{ id: "schema:ethdebug/format/context" }}
+  schema={{ id: "schema:ethdebug/format/program" }}
   />

packages/web/src/css/custom.css

@@ -59,3 +59,22 @@
   text-decoration: underline !important;
   background-color: inherit !important;
 }
+
+.theme-doc-sidebar-item-category.root-schema > * > a::after {
+  margin-left: 0.5em;
+  content: "Root schema";
+  width: min-content;
+  font-size: 66%;
+  font-weight: var(--ifm-font-weight-bold);
+  line-height: 1;
+  text-transform: uppercase;
+  background-color: var(--ifm-badge-background-color);
+  border: var(--ifm-badge-border-width) solid var(--ifm-badge-border-color);
+  border-radius: var(--ifm-badge-border-radius);
+  color: var(--ifm-color-primary-darkest);
+  padding: var(--ifm-badge-padding-vertical) var(--ifrm-badge-padding-horizontal);
+  transform: none;
+
+
+
+}

packages/web/src/schemas.ts

@@ -168,30 +168,30 @@ export const schemaIndex: SchemaIndex = {
     })).reduce((a, b) => ({ ...a, ...b }), {})
   ),
 
-  "schema:ethdebug/format/context": {
-    title: "ethdebug/format/context schema",
+  "schema:ethdebug/format/program/context": {
+    title: "ethdebug/format/program/context schema",
     href: "/spec/context"
   },
 
   ...([
     "code",
     "variables"
   ].map(name => ({
-    [`schema:ethdebug/format/context/${name}`]: {
+    [`schema:ethdebug/format/program/context/${name}`]: {
       href: `/spec/context/${name}`
     },
   })).reduce((a, b) => ({ ...a, ...b }), {})),
 
-  "schema:ethdebug/format/bytecode": {
-    title: "ethdebug/format/bytecode schema",
-    href: "/spec/bytecode"
+  "schema:ethdebug/format/program": {
+    title: "ethdebug/format/program schema",
+    href: "/spec/program"
   },
 
   ...([
     "instruction"
   ].map(name => ({
-    [`schema:ethdebug/format/bytecode/${name}`]: {
-      href: `/spec/bytecode/${name}`
+    [`schema:ethdebug/format/program/${name}`]: {
+      href: `/spec/program/${name}`
     },
   })).reduce((a, b) => ({ ...a, ...b }), {})),
 

schemas/info.schema.yaml

@@ -0,0 +1,45 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/info"
+
+title: ethdebug/format/info
+description: |
+  Objects in this schema organize debugging data relating to a particular
+  compilation, including **ethdebug/format/type** and
+  **ethdebug/format/pointer** records by name identifiers.
+
+  Objects in this schema **may** contain debugging information about individual
+  sources, contracts, and compiled bytecodes, to accommodate use cases that
+  benefit from debugging data being collected together in a single JSON object.
+type: object
+properties:
+  types:
+    title: Types by name
+    description: |
+      A collection of types by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/type"
+
+  pointers:
+    title: Pointer templates by name
+    description: |
+      A collection of pointer templates by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/pointer/template"
+
+  compilation:
+    $ref: "schema:ethdebug/format/materials/compilation"
+
+  programs:
+    type: array
+    items:
+      $ref: "schema:ethdebug/format/program"
+
+required:
+  - types
+  - pointers
+
+examples:
+  - types: {}
+    pointers: {}

schemas/materials/source-range.schema.yaml

@@ -26,10 +26,15 @@ properties:
     $ref: "schema:ethdebug/format/materials/reference"
 
   range:
+    title: Bytes range within source contents
+    description: |
+      Ranges that span the entire source contents **may** omit this field
+      as a shorthand. This field is otherwise **required**.
     type: object
     properties:
       offset:
-        description: Byte offset at beginning of range
+        description: |
+          Byte offset at beginning of range.
         $ref: "schema:ethdebug/format/data/unsigned"
 
       length:
@@ -46,7 +51,6 @@ unevaluatedProperties: false
 
 required:
   - source
-  - range
 
 examples:
   - source:

schemas/materials/source.schema.yaml

@@ -95,5 +95,4 @@ examples:
           }
       }
 
-    language:
-      Solidity
+    language: Solidity