feat: propagation_surfaces array + rejection_reason on get_media_buys (#4686, #4687)#4690
Merged
Merged
Conversation
…rfaces array (#4686) Replace the single-value enum capabilities.media_buy.impairment_propagation with the non-exclusive array capabilities.media_buy.propagation_surfaces. The enum couldn't express the common case where a seller propagates on both the buy snapshot AND fires webhooks — premium guaranteed sellers (GAM, FreeWheel, CM360) do both, but the previous enum forced a choice between 'snapshot' and 'webhook_only', creating an incentive to declare 'webhook_only' and dodge the snapshot-coherence bar. Surface values: snapshot — media_buy.health + impairments[] mirror on get_media_buys webhook — notification-type: impairment fires via push_notification_config out_of_band — channels outside AdCP entirely (email, dashboard, partner-specific feeds) Default when absent: ['snapshot']. Storyboard gating: scenarios grade not_applicable when propagation_surfaces does not include 'snapshot'. Pre-release breaking change — the original enum landed in #4685 but 3.1.0 hasn't released yet (GA 2026-05-29), so no deprecation cycle. Also documents the out_of_band semantic split (proper out-of-band vs mapping-gap-disguised-as-out-of-band) and prescribes documenting mappings rather than claiming out_of_band when the seller does have the data under a non-AdCP field name. Closes #4686. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tems (#4687) The field existed on core/media-buy.json but wasn't typed on the get-media-buys-response.json items — same gap-class as health + impairments[] fixed in #4685. Completed the full audit of core/media-buy.json against the response schema: every other field (media_buy_id, account, status, health, impairments, confirmed_at, cancellation, total_budget, packages, invoice_recipient, creative_deadline, revision, created_at, updated_at, ext) is already mirrored. With rejection_reason added, the response is complete with respect to the canonical media-buy fields. Response-only fields (currency, start_time, end_time, valid_actions, available_actions, history, augmented packages with delivery snapshots) remain — deliberately response-side, not on core/media-buy.json. Closes #4687. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three expert reviews (protocol, docs, product). Must-fix items: - Drop real-brand names from schema description and lifecycle.mdx (GAM/FreeWheel/CM360). Replaced with 'premium guaranteed sellers' generic descriptor. Playbook rule (no real brands in examples). - Add explicit 'empty array invalid' clarification to the propagation_surfaces description — minItems: 1 already enforces it, but readers don't always check the constraint block. - Fix stale adcp#4683 referent in dependency_impairment.yaml — the capability is no longer in #4683's shape; lifecycle.mdx is the live cross-reference and is sufficient on its own. Deferred (filed separately): - proprietary_field guidance follow-up so the description's SHOULD directive doesn't get lost. - Release notes callout for the value rename webhook_only → webhook in 3.1.0 GA notes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two 3.1.0 follow-ups from the #4685 expert-review batch — both addressing taxonomy/schema gaps before 3.1.0 GA (2026-05-29).
Issues closed
impairment_propagationenum aspropagation_surfacesnon-exclusive arrayrejection_reasononget_media_buysresponse (completes the core/media-buy.json audit)Commits
feat(media-buy): restructure impairment_propagation as propagation_surfaces array (#4686)capabilities.media_buy.impairment_propagationwith non-exclusive arraycapabilities.media_buy.propagation_surfaces. The enum forced a choice betweensnapshotandwebhook_only, but the common case is both — GAM, FreeWheel, CM360 mirror impairments on the buy snapshot AND fire webhooks. The previous shape created an incentive to declarewebhook_onlyto dodge the snapshot-coherence bar. The array lets sellers declare["snapshot", "webhook"]honestly.snapshot(graded by impairment.coherence storyboards),webhook(graded by webhook contract),out_of_band(offline agreement, not protocol-graded).["snapshot"]— preserves current behavior for sellers that don't declare.not_applicablewhenpropagation_surfacesdoes not include"snapshot".out_of_bandsemantic split: sellers with a mapping gap (data in API under a non-AdCP field name) SHOULD document the mapping rather than claimout_of_band.fix(media-buy): surface rejection_reason on get_media_buys response items (#4687)rejection_reasontoget-media-buys-response.json#/properties/media_buys/items/properties— same gap-class ashealth+impairments[]fixed in feat: 3.1.0 follow-ups — impairment_propagation, swap recovery, cardinality #4685.core/media-buy.jsonagainst the response schema. Every other field oncore/media-buy.jsonis already mirrored on the response items. After this patch, the response is complete with respect to canonical media-buy fields.One minor changeset (#4686, pre-release-breaking but additive in semantics) + one patch changeset (#4687).
Test plan
build:schemas✓ /build:compliance✓test:schemas✓ /test:examples✓test:storyboard-validations-paths✓ (only pre-existing brand-rights failure unchanged)test:storyboard-{doc-parity,check-enum,branch-sets,test-kits,sample-request-schema,response-schema,context-entity,contradictions,provides-state-for,auth-shape,advisory-expiry,raw-mode-required}✓Rollout
propagation_surfacesdefaults to["snapshot"]when absent — pre-3.1 sellers continue to be graded on snapshot coherence as today.impairment_propagationenum migrate single values to one-element arrays — five-second translation.propagation_surfaces, gradenot_applicablewhen"snapshot"is absent) is the adcp-client follow-up (adcp-client#1830 covers the related array_length check kind).🤖 Generated with Claude Code