Merge pull request #104 from ethdebug/data

Define schemas for data types (hex strings e.g.)

packages/web/spec/data/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "ethdebug/format/data",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Work-in-progress formal schema for ethdebug format"
+  }
+}

packages/web/spec/data/hex.mdx

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

packages/web/spec/data/overview.mdx

@@ -0,0 +1,30 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+:::tip[Summary]
+
+**ethdebug/format/data** is a namespace for schemas that define canonical
+representations of specific data types, such as hexadecimal strings and
+unsigned integers.
+
+Schemas in this namespace exist so that the rest of **ethdebug/format** has
+a consistent way of representing these types.
+
+:::
+
+## Reading these schemas
+
+The **ethdebug/format/data** 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.
+
+- [Hexadecimal strings](/spec/data/hex)
+- [Unsigned integer](/spec/data/unsigned)

packages/web/spec/data/unsigned.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Unsigned integers
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/data/unsigned" }}
+  />

packages/web/src/schemas.ts

@@ -156,6 +156,13 @@ export const schemaIndex: SchemaIndex = {
     }
   })).reduce((a, b) => ({ ...a, ...b }), {}),
 
+  ...(
+    ["hex", "unsigned"].map(name => ({
+      [`schema:ethdebug/format/data/${name}`]: {
+        href: `/spec/data/${name}`
+      }
+    })).reduce((a, b) => ({ ...a, ...b }), {})
+  ),
 
   "schema:ethdebug/format/materials/id": {
     title: "Identifier schema",

schemas/data/hex.schema.yaml

@@ -0,0 +1,14 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/data/hex"
+
+title: ethdebug/format/data/hex
+description: |
+  A `0x`-prefixed hexadecimal string. This value **must** contain at least one
+  hexadecimal character (`0x` by itself is not allowed).
+
+type: string
+pattern: "^0x[0-9a-fA-F]{1,}$"
+
+examples:
+  - "0x0000"
+  - "0x1"

schemas/data/unsigned.schema.yaml

@@ -0,0 +1,13 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/data/unsigned"
+
+title: ethdebug/format/data/unsigned
+description: |
+  A non-negative integer encoded as a JSON number.
+
+type: integer
+minimum: 0
+
+examples:
+  - 0
+  - 100

schemas/materials/source-range.schema.yaml

@@ -30,11 +30,11 @@ properties:
     properties:
       offset:
         description: Byte offset at beginning of range
-        type: number
+        $ref: "schema:ethdebug/format/data/unsigned"
 
       length:
         description: Number of bytes contained in range
-        type: number
+        $ref: "schema:ethdebug/format/data/unsigned"
 
     unevaluatedProperties: false
 

schemas/pointer/expression.schema.yaml

@@ -22,14 +22,12 @@ $defs:
       An unsigned number or a `0x`-prefixed string of hexadecimal digits
 
     oneOf:
-      - type: integer
-        description: A non-negative integer literal
-        min: 0
+      - description: A non-negative integer literal
+        $ref: "schema:ethdebug/format/data/unsigned"
 
-      - type: string
-        description: |
+      - description: |
           A `0x`-prefixed hexadecimal string representing literal bytes
-        pattern: "^0x[0-9a-fA-F]{1,}$"
+        $ref: "schema:ethdebug/format/data/hex"
 
     examples:
       - 5

schemas/type/elementary/bytes.schema.yaml

@@ -13,11 +13,10 @@ properties:
   kind:
     const: bytes
   size:
-    type: number
     description:
       The number of bytes in the bytes string. If this field is omitted, this
       type is the dynamic bytes string type.
-    minimum: 1
+    $ref: "schema:ethdebug/format/data/unsigned"
 required:
   - kind
 examples:

schemas/type/elementary/fixed.schema.yaml

@@ -12,12 +12,12 @@ properties:
   kind:
     const: fixed
   bits:
-    type: number
+    type: integer
     multipleOf: 8
     minimum: 8
     maximum: 256
   places:
-    type: number
+    type: integer
     description:
       How many decimal places, implying that a raw value `v` of this type
       should be interpreted as `v / (10**places)`

schemas/type/elementary/int.schema.yaml

@@ -12,7 +12,7 @@ properties:
   kind:
     const: int
   bits:
-    type: number
+    type: integer
     multipleOf: 8
     minimum: 8
     maximum: 256

schemas/type/elementary/ufixed.schema.yaml

@@ -12,12 +12,12 @@ properties:
   kind:
     const: ufixed
   bits:
-    type: number
+    type: integer
     multipleOf: 8
     minimum: 8
     maximum: 256
   places:
-    type: number
+    type: integer
     description:
       How many decimal places, implying that a raw value `v` of this type
       should be interpreted as `v / (10**places)`

schemas/type/elementary/uint.schema.yaml

@@ -12,7 +12,7 @@ properties:
   kind:
     const: uint
   bits:
-    type: number
+    type: integer
     multipleOf: 8
     minimum: 8
     maximum: 256