Add scalar to delivery-metrics (forecast-side declared, delivery-side missing)

[bokelley]

Follow-up to PR #3507 (missing scalars). Protocol expert review surfaced one genuine cross-side gap that was out of scope.

The asymmetry

forecastable-metric.json:23 and forecast-point.json:38 declare plays as the DOOH spots-played currency — buyers can request a forecast against plays. But the metric is absent from delivery-metrics.json and available-metric.json, so:

• Buyers can forecast plays but cannot reconcile against it in delivery
• The closest delivery-side equivalent is dooh_metrics.loop_plays, but that's a different denominator (per-screen rotation count, not total spot plays)

Proposal

Add plays to:

• static/schemas/source/core/delivery-metrics.json as type: integer, minimum: 0
• static/schemas/source/enums/available-metric.json
• The metric list in docs/media-buy/media-buys/optimization-reporting.mdx

Description: "Total spot plays delivered. Used for DOOH and broadcast inventory where the buyer reconciles against forecast plays (see forecastable-metric.json). Distinct from dooh_metrics.loop_plays, which is per-screen rotation count."

Same shape as the five scalars in #3507 — additive, optional, minor bump.

Reference

• PR feat(schemas): five missing metric scalars (CPCV, CPM, downloads, units_sold, new_to_brand_units) #3507 — five missing scalars; this is the sixth
• static/schemas/source/enums/forecastable-metric.json:23 — current plays declaration on the forecast side
• static/schemas/source/core/forecast-point.json:38 — same

[bokelley]

Triage

Classification: Feature request (schema addition)
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Gap confirmed; fix is directionally correct. Two structural questions need a decision before merging: (1) plays as a count should be integer if nested in dooh_metrics (where loop_plays is already integer) or number if top-level (where all count scalars — impressions, clicks, views — are number); (2) DOOH fields in OpenRTB 2.6 live in sub-objects, and dooh_metrics already exists for this purpose — top-level placement signals a universal metric but the description scopes it to DOOH/broadcast. Nit: add a delivery-side cross-reference sentence in forecastable-metric.json's existing plays description.
• adtech-product-expert: Workflow gap is real and plays is the correct term of art across DOOH platforms (Geopath/DPAA/OAAA language; used by Vistar, Place Exchange, Broadsign, VIOOH, TTD, DV360). Confirms available-metric.json must be updated for capability-discovery to work (already in scope). Nit: the description needs one more sentence explicitly distinguishing plays from dooh_metrics.loop_plays to prevent implementer confusion.

My take: Both experts agree the gap is real and this is the right fix. The open question is placement — top-level vs. inside dooh_metrics — which controls type, enum design, and capability-discovery granularity. @bokelley, your call: A or B?

---

Option A — Top-level field (as proposed, mirrors forecast-side shape):

// delivery-metrics.json — new top-level property (type: number, matches impressions/clicks/views pattern)
+   "plays": {
+     "type": "number",
+     "description": "Total spot plays delivered. Used for DOOH and broadcast inventory where the buyer reconciles against forecast `plays` (see `forecastable-metric.json`). Distinct from `dooh_metrics.loop_plays`, which is per-screen rotation count.",
+     "minimum": 0
+   },

// available-metric.json — new enum entry; sellers individually advertise plays support
    "new_to_brand_units",
+   "plays"

Reconciles directly with forecastable-metric.plays (same level, same name). Sellers can flag plays independently from dooh_metrics. Creates a second top-level DOOH/broadcast field outside the existing DOOH sub-object.

---

Option B — Nested inside dooh_metrics (DOOH fields stay cohesive):

// delivery-metrics.json — added inside the existing dooh_metrics sub-object (type: integer, matches loop_plays)
    "dooh_metrics": {
      "properties": {
        "loop_plays": { ... },
+       "plays": {
+         "type": "integer",
+         "description": "Total spot plays delivered across all screens and loops. Campaign-level aggregate; distinct from loop_plays (per-screen rotation count). Reconciles against forecast plays.",
+         "minimum": 0
+       },

available-metric.json unchanged — the existing dooh_metrics enum token already covers all sub-fields. Follows OpenRTB 2.6 DOOH sub-object pattern. Forecast reconciliation path from forecastable-metric.plays is one step less obvious. If plays is also needed for broadcast inventory (non-DOOH), this placement is incorrect and would need a separate sub-object.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01URQBpNjos3twrWQjJCsRt7

---

Generated by Claude Code