EcoCompute · Schema

The report contract, and the v1.3 environment draft

This page is part of the spec layer: the machine-checkable half of the protocol. The live schema is ecocompute-energy/1.3, maintained in the container repository at schema/energy.schema.json — the container validates every report it writes against it before emitting it. What follows is (a) what a valid report must contain today, (b) the draft environment block proposed for the v1.0 bar, and (c) the version-migration and compliance rules. A separate, much smaller schema describes the estimator's output — it is a tool response, not a measurement.

Why a schema at all. An energy number without its context (GPU, driver, stack, window, thermal state, replication) is unfalsifiable — there is nothing to check it against. The schema makes the context a required part of the number, so "a measurement" is a typed object, not a headline.

1 · Required today — `ecocompute-energy/1.3`

A report is schema-valid if and only if it passes validation against the live schema. The top-level required keys are:

schema_version          "ecocompute-energy/1.3"
benchmark               "ecocompute-energy-methodology"
scenario                "SingleStream" | "Offline"   (nominal, from batch size; not LoadGen-enforced —
                        scenario_note says so)
system_under_test       gpu, gpu_arch, accelerator_count, host
workload                model_name, params_b, precision, batch_size, context_length
measurement             method ("NVML on-device power sampling"), sample_rate_hz,
                        tokens_per_run, iterations, warmup
results                 total_energy_joules, tokens_generated, energy_per_token_mj,
                        avg_power_watts, throughput_tokens_per_s, basis
                        (+ fp16_energy_per_token_mj, vs_fp16_energy_pct when a
                        same-session FP16 baseline exists)

Conditional requirements the validator enforces: basis must be measured whenever measurement_source is direct-nvml; a report that fell back to dataset-derived values must name the fallback and must not claim measured. The software block records the full version set actually used and diffs it against the published pins — a run on a different stack is real, but is flagged as not directly comparable with pinned-image runs. Since 1.3, a power_trace block may carry whole-run 10 Hz sidecar CSVs with phase markers (load → quantization → warm-up → measure → quality), so the measurement window can be re-cut post hoc without re-running.

2 · Draft — the `environment` block for the v1.0 bar

Status: draft, open for comment (issue tracker). Not yet emitted by the container. Motivated by three gaps the 2026-09 sessions exposed:

Power limit and clocks were never recorded. The 2026-09-25 two-card re-test had to capture nvidia-smi -q -d POWER,CLOCK,PERFORMANCE manually; one session in August missed it entirely (post-hoc re-captured, and labelled as such). A card with a locked power limit is a different operating point.
Idle/cooldown temperature was not a field. Cold-start claims ("28 °C at start") lived in side logs, not in the report.
Physical card identity was not a field. The same re-test found the hosting platform had moved the instance to a different physical GPU between sessions (different UUID) — without the UUID we would have mis-filed a card-to-card difference as session-to-session noise.

"environment": {
  "gpu_uuid":            "GPU-ccb89dd1-33ae-1b76-f767-8fe2bd818af6",
  "power_limit_w":       450.0,
  "power_limit_source":  "nvml enforced power limit",
  "clocks_mhz": {
    "sm_start": 210,  "mem_start": 210,
    "sm_end":   2790, "mem_end":   10501
  },
  "temperature_c": {
    "idle_before": 28,        // after cooldown, before load — the cold-start claim
    "start":       28,
    "end":         41,
    "peak":        58
  },
  "clock_lock_applied":  false,
  "power_lock_applied":  false,
  "capture_method":      "nvidia-smi -q -d POWER,CLOCK,PERFORMANCE,TEMPERATURE"
}

Design rules: fields record the as-found operating point — the protocol says do not lock clocks or power to match historical data; record what the card was actually doing. idle_before is the cooldown gate (protocol: wait until the card returns to idle temperature before each arm). power_limit_source distinguishes the enforced NVML limit from a user override. Unavailable telemetry is null with a reason — never omitted silently, never invented.

3 · Compliance levels

"Valid" is not one binary. A report is graded at the highest level it satisfies — and each level is checked by a different mechanism, because the JSON schema can only see structure, not semantics:

Level	Name	Criteria	Checked by	What it may be used for
A	Schema-valid	Passes `ecocompute-energy/1.3` validation; all §1 required keys present and consistent (version-conditional: at 1.3, `tokens_per_run`/`iterations`/`warmup`/ `context_length`/`software` are required; `sample_rate_hz` ≥ 10)	the JSON schema	Overlay on the charts; browser-side comparison; archived as-is
B	Protocol-conformant (submittable)	Level A plus: every Protocol v1.1 MUST holds — same-session FP16 baseline (`vs_fp16_energy_pct` present), stated `basis: measured`, `measurement_source: direct-nvml`, batch 1 / 256 tokens / warm-up recorded, full `software` version set, thermal block present and honest (cooldown respected, or the violation disclosed in a note)	the semantic validator (`--profile v1.1-core`)	Publication in /replications/, credited; enters the next dataset release after review
C	Dataset-eligible (Standard-candidate, draft)	Level B plus: whole-run power-trace sidecar, achieved sample rate recorded, the §2 `environment` block complete (power limit, clocks, idle temperature, GPU UUID), and the configuration has n ≥ 3 independent sessions or ≥ 2 physical cards — cross-session/cross-card spread reported, not implied	validator (`--profile dataset-eligible`) plus dataset-level review — replication counts and cross-card spread live in the build CSV, not in one report	Counted toward the v1.0 micro-standard bar (per-configuration ≥3 sessions, ≥2–3 cards per architecture)

Schema-valid ≠ protocol-conformant. A report can pass the JSON schema and still violate the protocol — no thermal block, no FP16 baseline, fabricated-looking pin consistency. The schema cannot see cross-field semantics; that is what the validator is for. Run it on any report:

ecocompute validate --profile v1.1-core energy.json
# or: python3 tools/validate.py energy.json   (container repo)

# verdicts: schema-valid | protocol-conformant | dataset-eligible
# exit codes: 0 conformant · 1 schema-valid but violating (clause-numbered) · 2 schema-invalid

Honest failure states pass: steady_state_reached: false and thermal.basis: "unavailable" are valid reports of reality, not violations — only fabrication fails.

4 · Version migration and invalidation rules

Old reports are never rewritten. A v1.2 report stays v1.2; if its numbers are re-derived (window re-cut, baseline recomputation), the re-derivation is a new artifact with its own provenance entry, and the changelog records what moved and why. The 2026-09-24 window unification followed this rule: the llama.cpp row was re-cut into a new CSV, the original archive untouched.
Backward compatibility: v1.3 validators accept v1.2 reports (the added blocks are optional at v1.3); v1.2 validators reject v1.3 reports. Submissions at either version are accepted at compliance level A/B.
What invalidates a comparison (a pair of reports may both be valid yet not comparable): different software stacks (kernel changes move NF4/INT8 results — the 2026-09-20 5090 re-test is the worked example), different measurement windows, different thermal modes, locked vs unlocked clocks/power, or a workload field mismatch (batch, tokens, context). The site states the stack and window with every displayed number for exactly this reason.
Deprecation: a schema version is deprecated when a successor has been the container default for two releases; deprecated versions remain validatable forever (the validators are versioned with the schema), but new submissions at deprecated versions are flagged in review.
Failure tests: the container repository carries schema tests including deliberately malformed reports (missing results, basis: measured with a fallback source, mismatched scenario labels) that must fail validation. A schema change that lets any of them pass is itself a bug.
Pooling rule (data policy, not schema): supplementary sessions measured on a different stack are archived separately and never silently pooled into seed counts or fitted curves — versioning is by session archive, and the changelog entry says which counts, if any, a session entered.

5 · Machine-readable copies

Measurement report schema (live, 1.3): ecocompute-mlcube/schema/energy.schema.json — JSON Schema draft-07; the container runs builtin validation on every report.
Semantic validator (live): ecocompute-mlcube/tools/validate.py — checks every machine-checkable Protocol v1.1 MUST the schema cannot express, with clause-numbered violations. ecocompute validate --profile v1.1-core is the container alias. Its test suite includes the real 2026-09-25 re-test report, which it grades schema-valid but not protocol-conformant (thermal block not yet emitted by the container — tracked issue).
Environment block (draft, §2): proposed as ecocompute-energy/1.4-draft; tracked in the container issues; will land together with the container emitting the thermal block.
Estimator output schema: quantization-energy-report-schema.yaml — describes the /?tab=estimate tool response. It is a model output: its measurement_method field says "interpolated from measured anchors" and it must never be archived as a measurement.

The report contract, and the v1.3 environment draft

1 · Required today — ecocompute-energy/1.3

2 · Draft — the environment block for the v1.0 bar

3 · Compliance levels

4 · Version migration and invalidation rules

5 · Machine-readable copies

1 · Required today — `ecocompute-energy/1.3`

2 · Draft — the `environment` block for the v1.0 bar