Identification

Summary

ethdebug/format/data/identification is the canonical representation of what an object is. It contains the name of a schema and the version of the specification that defines that schema. An object carries it in an ethdebug field.

Each of the three root schemas, ethdebug/format/program, ethdebug/format/info and ethdebug/format/info/resources, includes ethdebug/format/data/identification under the key ethdebug. An object in any of these schemas may carry a field shaped like this:

{
  "ethdebug": {
    "schema": "ethdebug/format/program",
    "version": "<the current version>"
  }
}

schema is the name of the schema the object conforms to; each root schema pins this to its own name. The schema's $id is schema: followed by this name. version is the version of the ethdebug/format specification that defines schema.

Explore
View source
Playground

Loading ....

YAML
JSON

ethdebug/format/data/identification
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/data/identification"

title: ethdebug/format/data/identification
description: |
  Names the schema an object conforms to and the version of the
  specification that defines that schema.

  `schema` is the name of the schema; `version` is the version of the
  ethdebug/format specification that defines it. A producer writes the
  version of the specification whose schemas it targets. An object
  without this field predates it. Inside a container that carries the
  field, a nested object may omit it; if both carry it, their versions
  must be equal.

type: object

properties:
  schema:
    type: string
    title: Schema identifier
    description: |
      The name of the schema this object conforms to, for example
      `ethdebug/format/program`. The schema's `$id` is `schema:`
      followed by this name.

  version:
    type: string
    title: Specification version
    description: |
      The version of the ethdebug/format specification that defines
      `schema`, as a semver string without build metadata.
    pattern: "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$"

required:
  - schema
  - version

additionalProperties: false

examples:
  - schema: "ethdebug/format/program"
    version: "0.1.0-draft.0"

ethdebug/format/data/identification
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/data/identification",
  "title": "ethdebug/format/data/identification",
  "description": "Names the schema an object conforms to and the version of the\nspecification that defines that schema.\n\n`schema` is the name of the schema; `version` is the version of the\nethdebug/format specification that defines it. A producer writes the\nversion of the specification whose schemas it targets. An object\nwithout this field predates it. Inside a container that carries the\nfield, a nested object may omit it; if both carry it, their versions\nmust be equal.\n",
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "title": "Schema identifier",
      "description": "The name of the schema this object conforms to, for example\n`ethdebug/format/program`. The schema's `$id` is `schema:`\nfollowed by this name.\n"
    },
    "version": {
      "type": "string",
      "title": "Specification version",
      "description": "The version of the ethdebug/format specification that defines\n`schema`, as a semver string without build metadata.\n",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$"
    }
  },
  "required": [
    "schema",
    "version"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "schema": "ethdebug/format/program",
      "version": "0.1.0-draft.0"
    }
  ]
}

Rules

Which version to write

A producer writes the version of the specification whose schemas it targets.

Absent field

An object without this field predates it.

Nesting

A program nested inside an info document (at programs[i]) may omit the field. If both the info document and the program carry it, their version values must be equal.

The same rule applies to a program that sits beside a resources object.

For example, in solc's standard JSON output, evm.bytecode.ethdebug and evm.deployedBytecode.ethdebug are programs that sit beside the top-level ethdebug wrapper, whose resources member is the resources object.

Required later

The field is optional for now. It becomes required in the stable 0.1.0 release. ethdebug/format/program and ethdebug/format/info are closed objects (unevaluatedProperties: false), so the previous release's schemas reject an object that carries the field.

Resolution of names

A schema value of ethdebug/format/<path> names the schema whose source is schemas/<path>.schema.yaml in the ethdebug/format specification, at the version named alongside it. The schema's $id is schema:ethdebug/format/<path>. The $id is an identifier, not a web address, and emitted data should not place it in a $schema key: editors treat $schema as a URL and report an error.

Rules​

Which version to write​

Absent field​

Nesting​

Required later​

Resolution of names​