format: identify info, resources and program objects with their schema and specification version

[gnidan]

Info, resources and program objects can now say which schema they conform to and which version of the specification defines it:

{
  "ethdebug": {
    "schema": "ethdebug/format/program",
    "version": "0.1.0-draft.0"
  },
  "contract": { "...": "..." }
}

Info documents and resources objects must carry the field: both schemas list ethdebug in required. schema is the schema's name; its $id is schema: followed by that name. version is the version of the specification. ethdebug/format/data/identification defines the object, and each root pins schema to its own name. Because ethdebug/format/info references ethdebug/format/info/resources, the two do this with a 2020-12 dynamic reference: resources declares a $dynamicAnchor whose default is its own name, and info fills that anchor with "ethdebug/format/info". A standalone resources object therefore cannot claim to be info, and an info document cannot claim to be resources. This is the format's first use of dynamic references; the docs site's schema viewer resolves them to the constant each page's schema pins.

The schema: ids in the schema files stay as they are. They are identifiers in the JSON Schema sense, not web addresses, and they are deliberately not placed in a $schema key: JSON editors treat $schema as a URL and report an error for anything they cannot fetch, and no format we looked at (OpenAPI, SARIF, CycloneDX, SPDX) puts a custom-scheme URI there. A namespaced ethdebug object holds both parts without any parsing.

Where the field appears, per the new spec page:

• An info document and a resources object must carry it.
• A program inside an info document should not carry it; the info document identifies it.
• A program emitted outside an info document should carry it. In solc's standard JSON, the per-contract programs sit beside the top-level resources object.
• All objects of one compilation must name the same version.

program and info are closed objects (unevaluatedProperties: false), so the previous release's schemas reject an object that carries the field. The changelog entry marks this required: for producers and consumers.

Reference implementation, per the rule that a schema change is not done until the implementation supports it:

• @ethdebug/format exports Data.Identification and Data.isIdentification, identify() for producers, and version; Program gains the optional member.
• bugc emits the field on every program.
• conformance asserts that a program and its resources object name one version, and bugc's synthesized resources object carries the field. solc does not emit the field on its resources object yet, so the solc conformance test adds it to a copy before validating, and checks everything else as before. That test fails with a message to remove the workaround as soon as solc emits the field.
• bin/version.ts keeps the schema examples current: when the specification version moves, the bump rewrites the version literal in the examples in the same Publish commit. It refuses to run when no example carries the version, or when one carries a version other than the current one.

The schema-example handling is a release-tooling module, bin/release/schema-versions.ts, in an identification PR. It belongs here because this field is what put a version literal into the schema examples. The module finds the literals with one structural rule: under a schema's examples, any mapping whose schema names one of the format's schemas and that has a version beside it. It finds the sites by parsing the YAML and writes by splicing the original text, so the spec sources are never re-printed. Its test checks every literal against the current version and runs in the root suite.

Upstream: solc does not emit the field yet (see the conformance note above), and soldb ignores unknown keys. A heads-up issue follows this PR, noting that a solc program will read evm.bytecode.ethdebug.ethdebug because solc already uses ethdebug as its namespace key, and that resources objects must now carry the field.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://ethdebug.github.io/format/pr-preview/pr-305/
Built to branch gh-pages at 2026-10-02 00:57 UTC. Preview will be ready when the GitHub Pages deployment is complete.