feat(schemas): vendor-metric extensions surface for measurement metrics

[bokelley]

Summary

Resolves the closed/open available-metric.json enum question raised in #3460. Adds a structured parallel surface for vendor-defined metrics rather than opening the standard vocabulary to free-form strings.

The motivating use case: a buyer that needs Adelaide attention, Scope3 emissions, Nielsen DAR demographics, IAS/DV custom quality, brand-lift surveys, or in-flight attention panels — none of which fit the closed standard enum, but all of which need structured discovery + reporting.

Why structured, not open-string

Opening the closed enum to x_* strings would solve the asymmetry with delivery-metrics.json's additionalProperties: true posture but defeats discovery: a buyer asking "I need attention measurement" can't query a flat string namespace where Adelaide writes x_adelaide_attention_units, Lumen writes x_lumen_attention_seconds, and TVision writes x_tv_co_view_attention. A structured extension gives the buyer two queryable axes — vendor (BrandRef) and metric_category (an industry classification) — with the standard metric_name as a third pin once vendors converge.

Schemas added

• core/vendor-metric.json — descriptor: { vendor: BrandRef, metric_name, metric_category?, standard_reference? }. No agent_url — measurement-agent discovery defers to the vendor's brand.json agents[type='measurement'], matching the existing convention in measurement-terms.json and performance-standard.json (validated by both protocol expert and agentic architect on independent reviews).
• core/vendor-metric-value.json — reported value: { vendor, metric_name, value, unit?, measurable_impressions?, breakdown? }. The measurable_impressions field is the coverage denominator — vendor measurement is rarely 100% (Adelaide only scores impressions where their SDK fires, Nielsen DAR only matches panel-resolved impressions, IAS/DV only measure where their tag is present). This pattern parallels the existing viewability.measurable_impressions field that has handled vendor coverage in the IAS/DV/MRC ecosystem for over a decade. The breakdown slot accommodates structured payloads beyond a single scalar (Nielsen demographic breakouts, TVision co-view, iSpot incremental decomposition).
• enums/measurement-category.json — 9 values: attention, brand_lift, incrementality, audience, reach, creative_quality, emissions, outcomes, other. Tracks the established measurement-vendor space.

Wired in

• core/reporting-capabilities.json → new vendor_metrics array (parallel to available_metrics)
• core/product-filters.json → new required_vendor_metrics filter (each entry pins vendor, metric_name, metric_category, or any combination — at least one of three; AND across entries; cross-vendor query via metric_category; same filter-not-fail convention as siblings)
• core/delivery-metrics.json → new vendor_metric_values array (parallel to standard scalars; additionalProperties: true preserved on parent for migration)
• docs/media-buy/task-reference/get_products.mdx → new filter row
• docs/media-buy/task-reference/get_media_buy_delivery.mdx → new bullet under per-package
• docs/media-buy/media-buys/optimization-reporting.mdx → new Vendor-Defined Metrics section covering declaration, discovery, reporting, brand.json discovery anchor, the standards-driven promotion path, and v1 accountability scope

v1 accountability scope

Standard available_metrics are subject to the missing_metrics contract from #3472. Vendor metrics are advisory in v1 — buyers verify out-of-band via measurable_impressions coverage and direct calls to the vendor's measurement agent. The asymmetry reflects what the seller can credibly attest to: SSPs typically don't have Adelaide/Scope3 numbers in their delivery pipeline; those flow from the vendor's own infrastructure.

Promotion path

When the industry converges on a metric via a published standard (IAB Attention Measurement Guidelines, MRC variants, GARM emissions framework), the spec adds it to the closed available-metric.json enum and the vendor extensions become historical aliases. The standard_reference field anchors promotion to standards-body publications, not to ad-hoc vendor convergence counts.

Backwards compatibility

All additions are optional. Sellers without vendor metrics see no change. Closed available-metric.json enum unchanged. additionalProperties: true preserved on delivery-metrics.json so existing free-form vendor emissions remain conformant; structured vendor_metric_values is the recommended path going forward.

Pre-build expert review applied

Three experts reviewed the design before code was written. Key adjustments incorporated:

• Dropped description and documentation_url from on-product extension (architect: 50K-token context bloat in a typical get_products response — moved to brand.json, fetched lazily)
• currency → unit (free string accommodates score/seconds/persons/gCO2e/USD/etc. — product expert: single-currency field broke for non-monetary vendors)
• Added breakdown (free-form object) for Nielsen DAR / TVision co-view / iSpot incremental
• Added metric_category enum (architect + product expert: cross-vendor query via metric_name silently fails because vendors don't converge on names pre-standardization)
• Added standard_reference URI (product expert: "3+ vendors converge → promote" isn't how MRC/IAB standards actually emerge — wire promotion to published standards instead)
• Replaced parallel missing_vendor_metrics accountability array with measurable_impressions coverage on each value (per your prior note: missing-ness is a coverage question, not a binary, and viewability solved this a decade ago)

Test plan

• npm run build:schemas — clean
• npm run test:schemas — 7/7
• npm run test:examples — 34/34
• npm run test:json-schema — 255/255
• npm run test:composed — 32/32
• npm run typecheck — clean
• npm run build:compliance — storyboard lints all green
• precommit + pre-push — green

Deferred to follow-ups

• Vendor-side conformance storyboard (test agent doesn't yet support vendor-metric simulate_delivery — same gap as feat(schemas): required_metrics filter + missing_metrics accountability #3472)
• additionalProperties: true → false migration on delivery-metrics.json at next major
• supported_extensions discovery hint for capability discovery agents

Refs #3460. Closes the closed/open enum question.

🤖 Generated with Claude Code