Merge pull request #59 from ethdebug/definitions

Allow types to have definitions

schemas/type/base.schema.yaml

@@ -57,6 +57,7 @@ $defs:
           - $ref: "#/$defs/TypeWrapper"
           - $ref: "#/$defs/TypeWrapperArray"
           - $ref: "#/$defs/TypeWrapperObject"
+
     required:
       - kind
       - contains

schemas/type/complex/alias.schema.yaml

@@ -15,6 +15,8 @@ properties:
     const: alias
   contains:
     $ref: "schema:ethdebug/format/type/wrapper"
+  definition:
+    $ref: "schema:ethdebug/format/type/definition"
 
 required:
   - kind

schemas/type/complex/struct.schema.yaml

@@ -17,6 +17,8 @@ properties:
     type: array
     items:
       $ref: "#/$defs/MemberField"
+  definition:
+    $ref: "schema:ethdebug/format/type/definition"
 
 required:
   - kind

schemas/type/definition.schema.yaml

@@ -0,0 +1,45 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/definition"
+
+title: ethdebug/format/type/definition
+description: |
+  Object containing name and location information for a type.
+
+  This schema does not require any particular field, but it **must** contain
+  at least one property.
+
+type: object
+properties:
+  name:
+    type: string
+
+  source:
+    type: object
+    properties:
+      id:
+        type:
+          - string
+          - number
+      range:
+        type: object
+        properties:
+          offset:
+            type: number
+          length:
+            type: number
+
+anyOf:
+  - title: Required `name`
+    required:
+    - name
+  - title: Required `source`
+    required:
+    - source
+
+examples:
+  - name: Ballot
+    source:
+      id: 5
+      range:
+        offset: 10
+        length: 56

schemas/type/elementary/contract.schema.yaml

@@ -16,6 +16,9 @@ properties:
     description:
       If this field is omitted, this type represents an address whose
       payability is not known.
+  definition:
+    $ref: "schema:ethdebug/format/type/definition"
+
 oneOf:
   - properties:
       library:

schemas/type/elementary/enum.schema.yaml

@@ -17,6 +17,8 @@ properties:
       values are allowed here.
     type: array
     items: true
+  definition:
+    $ref: "schema:ethdebug/format/type/definition"
 
 required:
   - kind

tests/src/schemas.ts

@@ -15,6 +15,7 @@ const readSchemas = (): {
     "type/base.schema.yaml",
     "type/wrapper.schema.yaml",
     "type/reference.schema.yaml",
+    "type/definition.schema.yaml",
     "type/elementary/uint.schema.yaml",
     "type/elementary/int.schema.yaml",
     "type/elementary/bool.schema.yaml",

web/spec/type/concepts.mdx

@@ -155,6 +155,7 @@ possibly includes other fields alongside `"type"`.
     </TabItem>
   </Tabs>
 </details>
+
 ## Type wrappers and type references
 
 This schema defines the concept of a type wrapper and the related concept of a
@@ -213,3 +214,36 @@ must be a string or a number.
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/type/reference" }}
   />
+
+## Sometimes types are defined in code
+
+Languages provide certain kinds of types by way of allowing their definition
+in user (or runtime) code. These include [struct](/spec/type/complex/struct),
+[enum](/spec/type/elementary/enum), and [alias](/spec/type/complex/alias)
+types.
+
+Types with definition information **may** include a `definition` field that
+specifies the name of the type (its identifier) and/or the source location of
+its definition.
+
+:::note
+
+When extending the [base type schema](/spec/type/base) for custom kinds of
+types with definitions, these custom schemas **must** require the specification
+of such definitions by way of this same `definition` field and its associated
+schema.
+
+:::
+
+This format does not prohibit the inclusion of this `definition` field for any
+type, so as to support languages where array types, etc. may be defined by name
+directly. It is recommended, however, that
+compilers implementing this format **should** prefer to use
+[alias](/spec/type/complex/alias) type for the common case of assigning a name
+to a type expression.
+
+### Type definition schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/type/definition" }}
+  />

web/src/schemas.ts

@@ -3,6 +3,7 @@ import YAML from "yaml";
 import typeBaseSchemaYaml from "../../schemas/type/base.schema.yaml";
 import typeWrapperSchemaYaml from "../../schemas/type/wrapper.schema.yaml";
 import typeReferenceSchemaYaml from "../../schemas/type/reference.schema.yaml";
+import typeDefinitionSchemaYaml from "../../schemas/type/definition.schema.yaml";
 import typeElementaryUintSchemaYaml from "../../schemas/type/elementary/uint.schema.yaml";
 import typeElementaryIntSchemaYaml from "../../schemas/type/elementary/int.schema.yaml";
 import typeElementaryBoolSchemaYaml from "../../schemas/type/elementary/bool.schema.yaml";
@@ -26,6 +27,7 @@ export const schemaYamls = [
   typeBaseSchemaYaml,
   typeWrapperSchemaYaml,
   typeReferenceSchemaYaml,
+  typeDefinitionSchemaYaml,
   typeElementaryUintSchemaYaml,
   typeElementaryIntSchemaYaml,
   typeElementaryUfixedSchemaYaml,
@@ -72,6 +74,10 @@ export const schemaIndex: SchemaIndex = {
     title: "Type reference schema",
     href: "/spec/type/concepts#type-reference-schema"
   },
+  "schema:ethdebug/format/type/definition": {
+    title: "Type definition schema",
+    href: "/spec/type/concepts#type-definition-schema"
+  },
   "schema:ethdebug/format/type": {
     href: "/spec/type"
   },