feat(optimization-goal): vendor_metric kind for vendor-attested optimization (#4644)

[bokelley]

Draft — open for 7-day WG comment window before merge. Measurement vendors (DV, IAS, Adelaide, Kantar, Scope3, retail-media partners) invited to raise extension needs while the shape is still flexible.

Summary

Closes #4644. Adds `kind: "vendor_metric"` to the optimization-goal discriminator so buyers can bind goals to a specific vendor + metric_id end-to-end. Today's `metric` enum includes `attention_seconds` and `attention_score` as if seller-native, but DV/IAS/Adelaide/TVision/Lumen each define attention differently — a vendor-agnostic goal is unverifiable. This PR adds the proper vendor-bound shape and deprecates the vendor-agnostic enum values for removal at the next major.

The new shape is structurally parallel to the existing `event` kind (which binds buyer-attested conversion events) — same precedent, just for vendor-attested measurement instead.

What changed

Schema	Change
`core/optimization-goal.json`	Third `oneOf` branch: `kind: "vendor_metric"` with `vendor: BrandRef`, `metric_id`, `target: { cost_per
`core/vendor-metric-optimization.json` (new)	Per-product capability declaration — `supported_metrics: [{ vendor, metric_id, supported_targets[] }]` with `uniqueItems` on both array levels. Mirrors the structure of `reporting_capabilities.vendor_metrics`.
`core/product.json`	New `vendor_metric_optimization` property alongside `metric_optimization`. Same deprecation note added to `metric_optimization.supported_metrics` with mirrored MAY-reject prose.
`index.json`	Registry entry for the new schema.

Three-precondition rejection rule

Sellers MUST reject `vendor_metric` goals failing the capability or reporting-coherence preconditions; sellers SHOULD verify the discovery precondition:

1. Discovery (SHOULD this minor; MUST at next minor) — `metric_id` is in the vendor's published `measurement.metrics[]` catalog. Softened to SHOULD while measurement-vendor adoption of AdCP-conformant capability publication catches up.
2. Capability — `(vendor, metric_id)` is in the product's `vendor_metric_optimization.supported_metrics[]`, and `target.kind` is in the matching entry's `supported_targets`.
3. Reporting coherence — the package's `committed_metrics[]` includes a matching `{ scope: "vendor", vendor, metric_id }` entry. Optimization without committed reporting is unverifiable — the buyer can't grade a goal whose value the seller isn't contractually reported.

Symmetry across surfaces

Same `(vendor, metric_id)` key everywhere:

Surface	Field
Discovery	Vendor's `measurement.metrics[]`
Capability — reporting	Product's `reporting_capabilities.vendor_metrics`
Capability — optimization	Product's `vendor_metric_optimization.supported_metrics` (new)
Commitment	Package's `committed_metrics` (scope: vendor)
Optimization	Package's `optimization_goals` (kind: vendor_metric) (new)
Accountability	Package's `performance_standards.vendor`
Delivery — value	`vendor_metric_values`
Delivery — missing	`get-media-buy-delivery-response.json#/missing_metrics` (scope: vendor)

What this unblocks

• Attention — DV/IAS/Adelaide/TVision/Lumen each with their own metric_ids
• Brand lift — Kantar/Upwave/Cint panel-based optimization
• Emissions — Scope3/Good-Loop sustainability-bound buying
• Retail-media partner metrics — Amazon/Walmart Connect/Criteo proprietary scoring

Test plan

• `npm run build:schemas` (rebuilds dist)
• `npm run test:schemas` (540+ schemas, 7 checks pass)
• `npm run test:examples` (36 examples pass)
• `npm run test:json-schema` (260 in-doc JSON blocks pass)
• `npm run test:composed` (43 composed-schema checks pass)
• ajv-validated the new vendor_metric oneOf branch and the new vendor-metric-optimization shape on representative valid/invalid cases
• Confirmed existing `metric` and `event` goal kinds still validate
• pre-commit (test:unit, typecheck, etc.) green

WG comment window — explicit asks

While this PR is in draft, would especially like feedback on:

1. `qualifier` slot on the goal — DV has sub-models (Authentic Attention vs Quality Attention); Kantar has lift dimensions (awareness vs consideration). Should the goal carry a `qualifier` object now, or defer until a vendor has a concrete need?
2. Multi-vendor goals — should buyers be able to express "optimize for attention from Adelaide OR DV, whichever delivers"? Today: stack as two priority-tiered single-vendor goals. Anyone want first-class multi-vendor support?
3. Minimize-direction polarity (emissions) — `cost_per` and `threshold_rate` are upward-pushing by default. Emissions is the canonical minimize target. Should the schema add a `direction` field, or do sellers handle minimize-style metrics by interpreting low scores favorably? (Scope3's API today does this implicitly.)
4. Methodology versioning — vendors revise their models (Adelaide AU v1 → v2; DV's panel refreshes; Kantar's lift methodology). The `(vendor, metric_id)` key doesn't capture model version, so a goal set under v1 may be reported under v2. Should `committed_metrics.qualifier` gain a `vendor_methodology_version` key, or is this captured implicitly by the vendor's `measurement.metrics[]` catalog snapshot at commit time?
5. Measurement-fee pass-through — Adelaide/DV/IAS charge per-impression measurement fees; if the seller optimizes against them, who pays? Separate `price_breakdown` line, embedded in CPM, or buyer-direct? This belongs adjacent to the vendor binding, not after.

Defaults given here are conservative; happy to add to the design before merge if anyone raises a concrete adopter need.

Resolved on review

• Anchor slug for the new "Metric lifecycle" section — heading renamed to drop em-dash; deep links from conversion-tracking and taxonomy point at `#metric-lifecycle`.
• Stale example in conversion-tracking — replaced "Minimum attention time" example using deprecated `metric: "attention_seconds"` with the vendor_metric Adelaide example.
• Release notes — added a parallel sub-entry for feat(optimization-goal): vendor_metric kind for vendor-attested optimization (#4644) #4668 alongside the feat(delivery-metrics): viewability.viewed_seconds + reach_window (#4579 partial, #4580) #4618 delivery-reporting entry.
• Glossary — Optimization Goal entry now covers all three kinds.
• Schema tightening — `uniqueItems` on `supported_metrics` and `supported_targets`; `maximize_value` exclusion rationale documented; preconditions-are-runtime note added; deprecation prose symmetric between optimization-goal.json and product.json.
• Discovery precondition softening — protocol and product experts agreed the MUST was unenforceable today without a round-trip + caching story, and measurement vendors don't publish AdCP-conformant capability catalogs yet. Softened to SHOULD this minor; tightens to MUST at next minor.

🤖 Generated with Claude Code