Normalize `pricing_options[].model` → `pricing_model` (creative vs product discriminator naming)

[bokelley]

Issue: normalize pricing_options[].model → pricing_options[].pricing_model

Repo: adcontextprotocol/adcp
Type: schema / breaking-track-additive
Severity: medium (causes recurring drift in implementations)
Target: 3.x minor (additive) → 4.0 major (rename-only)

Problem

The same compound noun pricing_options[] carries two different discriminator field names depending on whose subtree it appears in:

• media-buy/get-products-response.json → products[].pricing_options[].pricing_model
• creative/list-creatives-response.json → creatives[].pricing_options[].model

Both are oneOf discriminators with overlapping enum values (cpm, flat_fee, percent_of_media, per_unit, custom). The two schemas were authored independently; the asymmetry survives because nobody re-reads adjacent schemas side-by-side.

This is a recurring source of implementation drift. We've observed:

1. SDK-built agents and human-written adapters omit model on creative pricing options because they pattern-match from the products surface (where the field is pricing_model).
2. AJV/strict-validation environments reject the response with /creatives/0/pricing_options/0/model: must have required property 'model'.
3. LLM-driven implementations (which read the spec once into context) routinely conflate the two — Claude-built agents in our @adcp/client skill matrix get this wrong on a majority of creative_ad_server storyboard runs.

OpenRTB has been chastised for the same pattern (bidfloor vs floor historically). It's worth fixing while AdCP is still inside the early-3.x window.

Proposal

Rename creative/list-creatives-response.json:creatives[].pricing_options[].model to pricing_model. Match the products surface.

Backwards compatibility:

• 3.x minor cycle: accept both field names. Schema becomes oneOf over model (deprecated, still valid) and pricing_model (preferred). Validators treat pricing_model as canonical when both are present.
• 4.0: remove model.

Authoring rationale for picking pricing_model (not model):

• More discoverable in IDE autocomplete (longer, less ambiguous).
• Already the established name in the products surface, which buyers see first in most flows.
• model is too generic — could conflict with future fields (model name, AI model id, etc.).

Files affected

• schemas/v3/creative/list-creatives-response.json (lines defining pricing_options[].model)
• Any bundled/ outputs derived from it
• Doc references in docs/v3/creative/list_creatives.md and any examples
• llms.txt entries for list_creatives

Validation

After the change, the cross-schema audit should pass: grep -r '"model"' schemas/v3/**/pricing_options* | grep -v pricing_model should return nothing.

Source

Surfaced during AdCP @adcp/client skill-matrix conformance runs (see adcontextprotocol/adcp-client issue #785) where this drift class accounts for ~25% of creative_ad_server storyboard failures. Independently confirmed by ad-tech protocol expert review.

Schema clarity grade for AdCP 3.0 discriminator consistency: B- (five of six discriminators consistent across domains; this is the one breaking the pattern).

[bokelley]

Part of #3090 (epic — AdCP 3.x spec drift bundle).

[bokelley]

Triage

Classification: RFC / proposal
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert (needs-clarification / oppose): The RFC's load-bearing "overlapping enum values" claim is incorrect — signal-pricing.json values (cpm, percent_of_media, flat_fee, per_unit, custom) and product-side values (cpm, vcpm, cpc, cpcv, cpp, cpa, flat_rate, time) are largely disjoint. x-entity-types.json explicitly documents vendor_pricing_option / product_pricing_option as intentionally scoped separately — the field-name difference may be correct-by-design. Blast radius is six surfaces consuming vendor-pricing-option.json, not one. IAB precedent (OpenRTB cattax) uses a three-step runway (add → require → remove), not the two-step proposed.
• adtech-product-expert (oppose): Found a live fixture bug — static/compliance/source/specialisms/creative-ad-server/index.yaml line 72 uses pricing_model but signal-pricing.json requires model. This likely explains the reported storyboard failure rate better than the schema asymmetry. The actual buyer flow never switches on the discriminator anyway; it only echoes pricing_option_id in report_usage.

My take: Both experts oppose the 3.x dual-name approach. The actionable near-term item is a fixture patch. The rename itself, if the working group wants it, belongs in 4.0-only. @bokelley, your call: Option A (patch now, defer the rename RFC) or Option B (scope rename as a 4.0-only clean break)?

Option A — patch the fixture, re-scope RFC to 4.0:

# static/compliance/source/specialisms/creative-ad-server/index.yaml:72
- pricing_model: "cpm"
+ model: "cpm"

Fixes the probable failure source immediately. The RFC returns to 4.0 scoping with a corrected enum-overlap claim and all six vendor-pricing-option.json consumers enumerated.

Option B — 4.0-only clean break (drop the 3.x dual-name period):

# signal-pricing.json — all five variant branches
- "model": { "type": "string", "const": "cpm" }
+ "pricing_model": { "type": "string", "const": "cpm" }

Single rename at 4.0. Avoids two years of validator ambiguity from a dual-discriminator grace period. Requires an updated RFC covering all six affected surfaces and alignment with the IAB three-step normalization runway.

---

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

---

Generated by Claude Code

[bokelley]

Closing per Option A from the bot triage.

Why: The RFC's load-bearing claim (overlapping enum values across creative and product surfaces) doesn't hold up. signal-pricing.json (creative side, via vendor-pricing-option.json) and pricing-option.json (product side) have largely disjoint enum values — x-entity-types.json documents vendor_pricing_option vs product_pricing_option as intentionally scoped separately. The naming difference is correct-by-design, not drift.

The actual root cause of the storyboard failure rate the RFC was diagnosing is a fixture bug at creative-ad-server/index.yaml:72 that uses pricing_model where the schema requires model (and rate where it requires cpm). That patch is filed as a small follow-up issue.

If we still want a true rename for clarity, it's a 4.0-only clean break — six vendor-pricing-option.json consumer surfaces, IAB three-step runway (add → require → remove), no two-year dual-discriminator grace period. Not in 3.x.

Closing.