RFC: success variants of media-buy responses need a warnings[] channel for advisory non-blocking signals

[bokelley]

Background

The Submitted variants of create_media_buy_response, update_media_buy_response, and sync_creatives_response already include an optional errors[] array documented as:

Optional advisory errors accompanying the submitted envelope. Use only for non-blocking warnings (e.g., throttled_severity advisories, governance observations). Terminal failures belong in the error branch, not here.

The corresponding synchronous Success variants (CreateMediaBuyResponse1, UpdateMediaBuyResponse1, etc.) have no equivalent. Sellers running pre-flight checks on accepted-but-suboptimal buys have nowhere spec-compliant to surface advisory warnings.

Real-world use case

Two examples from salesagent (Prebid AdCP reference implementation):

1. Inventory overbook detection. A create_media_buy whose implied impression goal exceeds GAM's availability forecast is technically valid (GAM accepts it via ApproveAndOverbookOrders), but delivery will under-perform. The seller has the forecast result at request time and wants to tell the buyer "your goal of 80,000 impressions exceeds our forecast of 11,428 — your line item will land in INVENTORY_RELEASED." This is exactly the "non-blocking warning" semantic the Submitted variant's errors[] exists for, but the seller is on the synchronous Success path here, not Submitted.

2. Pricing rate above floor. A buyer's bid is accepted but is materially above the publisher's typical clearing rate. The seller wants to flag "you may be overpaying" without rejecting the buy.

Today's workarounds

Sellers either:

• (a) Reject buys that should succeed (loses revenue, bad buyer experience);
• (b) Hide warnings server-side in logs (useless to the buyer);
• (c) Put warnings in ext (acceptable per spec but not cross-implementation discoverable; every buyer has to know your ext keys).

Option (c) is what salesagent will ship for the overbook case in the short term, with a comment pointing at this RFC.

Proposed addition

Add an optional warnings: list[Error] to the synchronous Success variants of:

• create_media_buy_response
• update_media_buy_response
• sync_creatives_response

Same advisory-only semantics as the Submitted variant's errors[]. The Error shape is reused — code carries a registry value, message carries a human-readable explanation, details carries structured diagnostics.

{
  "warnings": {
    "type": "array",
    "items": { "$ref": "#/definitions/Error" },
    "description": "Optional advisory warnings accompanying a successful response. Non-blocking — the operation succeeded but the seller is surfacing context the buyer may want to act on. Terminal failures still belong in the error response variant, not here."
  }
}

Suggested initial code registry

A non-exhaustive set worth standardising so buyers can build cross-seller logic against them:

Code	Surface	Meaning
inventory_overbook_minor	create_media_buy success	Seller's forecast indicates goal exceeds available inventory
pricing_rate_above_floor	create_media_buy / update_media_buy success	Buyer's rate is materially above seller's clearing rate
creative_format_atypical	sync_creatives success	Asset accepted but doesn't match the format's typical shape
flight_dates_outside_pacing_window	update_media_buy success	New flight bounds make the existing budget pace unreasonably

Each entry would be defined separately (description, recommended details keys, examples). The registry can grow over time the same way error codes do.

Why not just errors[] on Success too?

Two reasons not to overload errors[]:

1. The success path semantically isn't an error condition. Putting advisory information under a key called errors reads wrong to anyone scanning the response.
2. The Submitted variant's errors[] is already documented as doing double duty (advisory ∪ terminal-but-deferred). Adding a third meaning on the Success path further muddies it.

A separate warnings key keeps the semantics clean: errors fail, warnings inform.

Compatibility

Optional field, default null, fully backward-compatible. Implementations that don't emit warnings are unaffected. Buyers that don't read the field are unaffected. Existing schemas already use extra='allow' (or equivalent JSON Schema additionalProperties: true) on these response types, so the wire shape doesn't break.

Relationship to ext

The ext extension mechanism is the right answer for seller-specific advisory data with no cross-implementation contract. warnings would carry the standardised advisory channel — registry-coded, semantics defined by the spec, discoverable across sellers. Both have a place; this RFC is about giving the standardised channel a home on the success path, where today only ext exists.

Salesagent context

Salesagent will ship the overbook detection feature in the next few days using ext.warnings as the temporary surface. If/when this RFC lands and propagates through adcp-client-python, swapping to first-class warnings[] is a one-line change. Happy to contribute a draft schema PR if useful — let me know.

[bokelley]

Triage

Classification: Feature request / RFC
Bucket(s): spec / protocol, media-buy
Status: ready-for-human

My take: RFC is factually accurate — CreateMediaBuySuccess explicitly forbids errors[] via a schema not constraint, leaving no spec-compliant advisory channel on the sync success path. The addition is non-breaking (additive optional field, minor bump) and the use case is compelling, but the WG needs to settle one design question before implementation.

Design question for WG vote:

Option A — Reuse Error shape (as proposed):

// CreateMediaBuySuccess variant
+ "warnings": {
+   "type": "array",
+   "items": { "$ref": "/schemas/core/error.json" },
+   "description": "Optional advisory warnings. Non-blocking."
+ }

Fastest path; codegen free-rides on existing type. code/message/details maps cleanly. Trade-off: items typed as error.json reads awkward for non-error signals.

Option B — New Warning schema (clean separation):

// new: static/schemas/core/warning.json (mirrors Error shape, distinct type)
+ "warnings": { "type": "array", "items": { "$ref": "/schemas/core/warning.json" } }

Semantics are clean — errors fail, warnings inform. Adds one core schema + SDK surface across adcp-client-python and adcp-go. Higher coordination cost, but sets a cleaner precedent.

@bokelley — WG call: Option A for 3.1 given salesagent urgency, or Option B through a full design cycle?

---

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

---

Generated by Claude Code

[bokelley]

3.2 decision: use a dedicated Warning schema, not Error items under a differently named array.

Proposed diff:

• add core/warning.json with registry-backed code, human-readable message, optional structured details, and ext;
• add optional warnings[] only to synchronous success arms for create_media_buy, update_media_buy, and sync_creatives;
• explicitly exclude warnings from terminal error arms and keep terminal failures in errors[];
• document that warnings never change operation success and buyers may ignore unknown warning codes;
• add success-with-warning and terminal-error conformance vectors plus SDK codegen coverage.

Do not add the suggested business-specific codes in the same PR unless each has independently ratified semantics/details. The first PR establishes the channel cleanly.