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": "schema:ethdebug/format/program",
    "version": "0.1.0-draft.0"
  },
  "contract": { "...": "..." }
}

The field is optional now and becomes required at the stable 0.1.0 release. An object without it predates the field. The schema part is the schema's $id; the version part is the version of @ethdebug/format the producer was built against. A new shared schema, ethdebug/format/identification, defines the object, and each root pins schema with a const (info/resources accepts either its own id or info's, because an info document is also a resources object).

The schema: ids stay as they are. They are identifiers in the JSON Schema sense, resolved through the @ethdebug/format package's schemas map, not web addresses. 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.

Rules, on the new spec page:

• A producer writes the version it was built against.
• Inside a container, a nested program may omit the field; when both carry it, the versions must be equal. In solc's standard JSON the resources object plays the container's role for the per-contract programs beside it.
• A consumer rejects an object only when its compatibility key differs from the one it supports, where the key is the major version, or major.minor while the major is 0 (semver treats 0.x minors as breaking). Within a key it accepts every version and may warn when the version is newer than the one it was built against. Drafts within one key are not distinguished: the field tells a consumer which changelog entries apply, it does not enforce them.

One consequence worth knowing: program and info are closed objects (unevaluatedProperties: false), so a consumer that validates against the previous release's schemas rejects an identified object until it updates its schemas. The changelog entry and the spec page state this; the entry keeps Consumers: optional:, in line with the earlier entries for new optional keys on closed objects, since a consumer that does not validate is unaffected.

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

• @ethdebug/format exports version (generated from package.json at build time), Identification and isIdentification (which checks the same semver pattern as the schema), identify() for producers and supports() for the consumer rule; Program gains the optional member.
• bugc emits the field on every program.
• programs-react exposes a specification verdict in its trace state and warns once on a newer version; the docs site's trace viewer shows a notice instead of the panels for an unsupported one. It never throws on the render path.
• conformance asserts that a program and its resources object name one version, and bugc's synthesized resources object carries the field.
• bin/version.ts keeps the schema examples honest: when @ethdebug/format moves, the bump rewrites the version literal in the examples in the same Publish commit, and refuses to run if the number of literals does not match the number of example sites. A format unit test asserts that every example literal equals the package version.

Upstream: neither solc nor soldb is affected by the optional field today (solc emits none; 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 the field becomes required at 0.1.0.

[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-09-22 00:42 UTC. Preview will be ready when the GitHub Pages deployment is complete.