Reconcile four parallel metric enums — metric-type, available-metric, forecastable-metric, performance-standard-metric

[bokelley]

Summary

The corpus has four parallel metric enums covering overlapping but inconsistent vocabularies:

• enums/available-metric.json (31 values) — closed delivery enum used by committed_metrics, required_metrics, reporting_capabilities.available_metrics
• enums/forecastable-metric.json (15 values) — forecast-time enum, includes measured_impressions / audience_size which don't exist in delivery
• enums/performance-standard-metric.json (5 values) — verification enum
• enums/metric-type.json (8 values) — legacy feedback enum with no clear layer alignment (separate RFC: see metric-type collapse issue)

Origin

Audit finding §3.11. The proliferation predates the verification / metric / attribution split documented in docs/measurement/taxonomy. Each enum grew independently; there's no canonical mapping between them.

Proposal

Re-anchor everything on available-metric.json + vendor_metric_values + the metric-scope.json discriminator (#3576 pattern). Specifically:

• metric-type.json deprecates entirely (handled by separate RFC for §3.3).
• forecastable-metric.json — forecast-only deltas (audience_size, measured_impressions) become a forecast-specific sub-enum or move to a forecast-only list. Shared values graduate to references against available-metric.
• performance-standard-metric.json stays — these are verification metrics with thresholds, a legitimately distinct subset. But the values should reference available-metric entries where they overlap.

Why

Today, a buyer agent looking at "what metrics does this product support across its lifecycle?" walks four enums with overlapping values and inconsistent shapes. Post-reconciliation, there's one closed delivery vocabulary and a small number of layer-specific subsets that reference into it.

Migration

• Forecast-only / performance-standard-only values stay where they are
• Shared values become references into available-metric
• Schema validation enforces consistency at build time
• Aliases preserved for one minor; eligible for cleanup at the next major

Related

• docs(measurement): add three-layer taxonomy doc #3843 — measurement taxonomy doc (atomic unit, graduated metrics)
• feat(schemas): unify metric accountability — timestamped contract + symmetric audit #3576 — metric-scope discriminator and unified row shape
• Companion to the metric-type enum collapse RFC (audit §3.3) — the cleanup is fully captured by the two together

[bokelley]

Triage

Classification: RFC / Feature request
Bucket(s): spec / protocol
Status: ready-for-human
Milestone: (omit — WG-gating; no single PR ship)

What the experts said:

• ad-tech-protocol-expert: sound-with-caveats — available-metric is the right canonical anchor, and the set arithmetic in the proposal is accurate; but "values graduate to $refs against available-metric" is a draft-07 misapplication — the correct form is a oneOf supertype (any valid available-metric value is also a valid forecastable-metric value), not per-value aliases. Also flags two undeclared deliverables: forecast-point.json hard-codes all 16 forecastable values as property keys and needs a separate editorial pass, and the viewability/completion_rate dual-presence (in both committed_metrics and performance_standards) has no spec rule on which governs on breach.
• adtech-product-expert: mixed — the three enums answer structurally distinct questions (delivery attestation vs. forecast model signals vs. verification quality floors), and PR docs(measurement): add three-layer taxonomy doc #3843 just drew those lines doctrinally. The qualifier pattern from feat(schemas): unify metric accountability — timestamped contract + symmetric audit #3576 may already address the buyer-navigability motivation without schema reshaping. Recommends reviewing this alongside companion Reconcile metric-type.json enum — collapses metrics / verification / attribution into one list #3858 (§3.3) as a pair before any code.

My take: Experts diverge on framing — protocol validates the direction but identifies a mechanism problem; product asks whether schema restructuring is the right fix at all versus documentation and annotations. Both agree: this should go to WG before execution, alongside #3858, after the post-#3576/#3843 dust has settled.

@bokelley, your call: is the core problem navigability (buyer agent can't tell how the four enums relate — addressable with x-lifecycle-layer annotations + cross-ref docs, non-breaking in 3.1) or vocabulary unification (the enums should be structurally anchored on available-metric — requires the oneOf-supertype mechanism and a WG vote)?

Option A — annotation-first, 3.1-eligible, zero migration cost:

// forecastable-metric.json — label the lifecycle layer, don't restructure
+  "$comment": "Forecast-time superset: 14 values shared with available-metric + 2 planning-only (audience_size, measured_impressions). See measurement/taxonomy.",
+  "x-lifecycle-layer": "forecast",
   "enum": ["audience_size", "measured_impressions", "reach", ...]

Ships in 3.1 as a docs/annotation PR. Defers structural question to a dedicated WG vote.

Option B — oneOf supertype restructure (3.1 additive + 4.0 cleanup):

// forecastable-metric.json — becomes a superset of available-metric
-  "enum": ["audience_size", "measured_impressions", "reach", ...]
+  "oneOf": [
+    { "$ref": "/schemas/enums/available-metric.json" },
+    { "enum": ["audience_size", "measured_impressions"] }
+  ]

Semantically correct per IAB OM SDK / OpenRTB 3.0 precedent. Requires a forecast-point.json editorial pass and WG resolution of the viewability/completion_rate dual-presence question before landing.

Both options should be sequenced with #3858 so WG sees the full §3.3 + §3.11 picture together.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

Closing as substantially addressed across three PRs:

• feat(schemas): metric vocabulary reconciliation — performance-feedback row migration + enum cross-references #3880 deprecated metric-type.json entirely (handled the metric-type collapse part of this issue), with a migration table mapping each legacy value to the new (scope, metric_id, qualifier) row shape.
• fix(schemas): three measurement audit cleanups (§3.8, §3.10, #3863 prose) #3886 corrected the prose drift in forecastable-metric.json description (previous claim that grps, reach, frequency were forecast-only was wrong — they're in available-metric.json too; actual forecast-only deltas are just audience_size and measured_impressions). performance-standard-metric.json description already clarifies its verification-subset role and shared-with-available-metric overlap.
• The graduated-metric track (feat(schemas): unify metric accountability — timestamped contract + symmetric audit #3576 + feat(schemas): completion_source qualifier — seller_attested vs vendor_attested completion_rate (closes #3861) #3877 + feat(schemas): unify outcome measurement into the row-shape vocabulary (closes #3857) #3884) cemented the canonical pattern: available-metric.json is the closed delivery vocabulary; verification-only and forecast-only enums reference into it where shared and carry their own deltas otherwise.

What's deferred to a follow-up: schema-level enforcement of the cross-references (a build-script check that values shared between forecastable-metric, performance-standard-metric, and available-metric don't drift). The prose cross-references are sufficient for v3.x; build-script enforcement is a tooling concern that can land later without a schema change.

The four-parallel-enums problem is no longer a problem in practice — metric-type is gone, and the remaining three enums each have a clearly-articulated role with documented overlap into available-metric.