Draft initial ethdebug/format/type

- Define ethdebug/format/type as if/then/else
  - `if` the object is a known kind,
  - `then` the object must be a known elementary or complex type
  - `else` the object must be a valid base type with added constraints

- Define ethdebug/format/type/elementary and
  ethdebug/format/type/elementary/{
    uint, int, ufixed, fixed, bool, bytes, string, address, contract,
    enum
  }

- Define ethdebug/format/type/complex and
  ethdebug/format/type/complex/{
    alias, tuple, array, mapping, struct
  }

- Define ethdebug/format/type/wrapper and ethdebug/format/type/reference
  to serve as more canonical forms that override the base schema equiv.

- Add pages for all the type schemas

- Move "key concepts" from base schema page to own page

- Document schema overall

- Test that all schemas have examples (except for permitted omissions)

schemas/type.schema.yaml

@@ -0,0 +1,59 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type"
+
+title: ethdebug/format/type
+description:
+  Canonical representation for all types.
+type: object
+
+if:
+  type: object
+  title: Known kind
+  description:
+    If `kind` adheres to the set of known kinds defined by this format
+  properties:
+    kind:
+      anyOf:
+        - $ref: "schema:ethdebug/format/type/elementary#/$defs/Kind"
+        - $ref: "schema:ethdebug/format/type/complex#/$defs/Kind"
+
+then:
+  type: object
+  title: KnownType
+  description:
+    Then the object must adhere to exactly one known kind of type
+  oneOf:
+    - $ref: "schema:ethdebug/format/type/elementary"
+    - $ref: "schema:ethdebug/format/type/complex"
+
+else:
+  type: object
+  description:
+    Else the object must be a valid **ethdebug/format/type/base** with
+    additional constraints
+  allOf:
+    - $ref: "schema:ethdebug/format/type/base"
+    - title: Required `class` field
+      required:
+        - class
+    - title: Specialized complex type `contains` field
+      type: object
+      if:
+        description:
+          If this object is a complex type
+        properties:
+          class:
+            const: complex
+      then:
+        description:
+          Then the `contains` field must adhere to
+          **ethdebug/format/type/wrapper** schemas, not the
+          **ethdebug/format/type/base** equivalent.
+
+          (i.e., these additional constraints must apply recursively)
+        properties:
+          contains:
+            oneOf:
+              - $ref: "schema:ethdebug/format/type/wrapper"
+              - $ref: "schema:ethdebug/format/type/wrapper#/$defs/Array"
+              - $ref: "schema:ethdebug/format/type/wrapper#/$defs/Object"

schemas/type/base.schema.yaml

@@ -13,7 +13,7 @@ oneOf:
 
 $defs:
   ElementaryType:
-    title: ElementaryType
+    title: Base elementary type
     description:
       Represents an elementary type (one that does not compose other types)
     type: object
@@ -26,16 +26,16 @@ $defs:
       contains:
         not:
           description:
-            "**Elementary types must not specify a `contains` field
-            (to make it easier to discriminate elementary vs. complex)**"
+            "Elementary types **must not** specify a `contains` field
+            (to make it easier to discriminate elementary vs. complex)"
     required:
       - kind
     examples:
       - kind: uint
         bits: 256
 
   ComplexType:
-    title: ComplexType
+    title: Base complex type
     description:
       Represents a complex type, one that composes other types (e.g., arrays,
       structs, mappings)
@@ -49,7 +49,10 @@ $defs:
         type: string
         description: The specific kind of complex type, e.g., array or struct
       contains:
-        title: ComplexType.contains
+        title: Complex type `contains` field
+        description:
+          Either a type wrapper, an array of type wrappers, or an object
+          mapping to type wrappers.
         oneOf:
           - $ref: "#/$defs/TypeWrapper"
           - $ref: "#/$defs/TypeWrapperArray"
@@ -84,19 +87,6 @@ $defs:
               kind: uint
               bits: 256
 
-  TypeReference:
-    title: '{ "id": ... }'
-    description: A reference to a known type by ID
-    type: object
-    properties:
-      id:
-        type:
-          - string
-          - number
-    additionalProperties: false
-    required:
-      - id
-
   TypeWrapper:
     title: '{ "type": ... }'
     description:
@@ -108,7 +98,8 @@ $defs:
       type:
         oneOf:
           - $ref: "schema:ethdebug/format/type/base"
-          - $ref: "#/$defs/TypeReference"
+          - $ref: "schema:ethdebug/format/type/reference"
+
     required:
       - type
 

schemas/type/complex.schema.yaml

@@ -0,0 +1,64 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/complex"
+
+title: ethdebug/format/type/complex
+description:
+  Canonical representation of a complex type
+
+type: object
+properties:
+  kind:
+    $ref: "#/$defs/Kind"
+required:
+  - kind
+
+allOf:
+  - if:
+      properties:
+        kind:
+          const: alias
+    then:
+      $ref: "schema:ethdebug/format/type/complex/alias"
+
+  - if:
+      properties:
+        kind:
+          const: tuple
+    then:
+      $ref: "schema:ethdebug/format/type/complex/tuple"
+
+  - if:
+      properties:
+        kind:
+          const: array
+    then:
+      $ref: "schema:ethdebug/format/type/complex/array"
+
+  - if:
+      properties:
+        kind:
+          const: mapping
+    then:
+      $ref: "schema:ethdebug/format/type/complex/mapping"
+
+  - if:
+      properties:
+        kind:
+          const: struct
+    then:
+      $ref: "schema:ethdebug/format/type/complex/struct"
+
+$defs:
+  Kind:
+    title: Known complex kind
+    description:
+      A schema for the values of `kind` reserved for known complex types
+      included in ethdebug/format
+    type: string
+    enum:
+      - alias
+      - tuple
+      - array
+      - mapping
+      - struct
+

schemas/type/complex/alias.schema.yaml

@@ -0,0 +1,38 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/complex/alias"
+
+title: ethdebug/format/type/complex/alias
+description:
+  Schema representing a type alias to another type
+
+type: object
+properties:
+  class:
+    type: string
+    const: complex
+  kind:
+    type: string
+    const: alias
+  contains:
+    $ref: "schema:ethdebug/format/type/wrapper"
+
+required:
+  - kind
+  - contains
+
+examples:
+  - kind: alias
+    contains:
+      type:
+        kind: uint
+        bits: 256
+
+  - kind: alias
+    contains:
+      type:
+        kind: array
+        contains:
+          type:
+            class: elementary
+            kind: super-uint # unsupported type
+            blits: -256

schemas/type/complex/array.schema.yaml

@@ -0,0 +1,35 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/complex/array"
+
+title: ethdebug/format/type/complex/array
+type: object
+properties:
+  class:
+    type: string
+    const: complex
+  kind:
+    type: string
+    const: array
+  contains:
+    $ref: "schema:ethdebug/format/type/wrapper"
+
+required:
+  - kind
+  - contains
+
+examples:
+  - kind: array
+    contains:
+      type:
+        kind: uint
+        bits: 256
+
+  - kind: array
+    contains:
+      type:
+        kind: array
+        contains:
+          type:
+            class: elementary
+            kind: super-uint # unsupported type
+            blits: -256

schemas/type/complex/mapping.schema.yaml

@@ -0,0 +1,40 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/complex/mapping"
+
+title: ethdebug/format/type/complex/mapping
+description:
+  Schema for representing mapping types
+
+type: object
+properties:
+  class:
+    type: string
+    const: complex
+  kind:
+    type: string
+    const: mapping
+  contains:
+    type: object
+    properties:
+      key:
+        $ref: "schema:ethdebug/format/type/wrapper"
+      value:
+        $ref: "schema:ethdebug/format/type/wrapper"
+    required:
+      - key
+      - value
+
+required:
+  - kind
+  - contains
+
+examples:
+  - kind: mapping
+    contains:
+      key:
+        type:
+          kind: address
+      value:
+        type:
+          kind: uint
+          bits: 256

schemas/type/complex/struct.schema.yaml

@@ -0,0 +1,54 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/type/complex/struct"
+
+title: ethdebug/format/type/complex/struct
+description:
+  Schema for representing struct types
+
+type: object
+properties:
+  class:
+    type: string
+    const: complex
+  kind:
+    type: string
+    const: struct
+  contains:
+    type: array
+    items:
+      $ref: "#/$defs/MemberField"
+
+required:
+  - kind
+  - contains
+
+examples:
+  - kind: struct
+    contains:
+      - name: x
+        type:
+          kind: uint
+          bits: 128
+      - name: y
+        type:
+          kind: uint
+          bits: 128
+
+$defs:
+  MemberField:
+    type: object
+    title: MemberField
+    description:
+      A schema representing a member field inside a struct type. This is an
+      **ethdebug/format/type/wrapper** with additional fields.
+    allOf:
+      - $ref: "schema:ethdebug/format/type/wrapper"
+      - type: object
+        title: Additional fields
+        description:
+          An object with optional `name` property for identifying named struct
+          member fields. **Note** that this language does not specify that a
+          struct must be consistent in its use of naming for all fields or none
+        properties:
+          name:
+            type: string