feat(schema): address 17 schema gaps that block autonomous agent operation by bokelley · Pull Request #1252 · adcontextprotocol/adcp

bokelley · 2026-02-27T03:13:42Z

Summary

Resolves 17 must-have schema gaps identified in issues #1223-#1239 that prevent agents from operating autonomously, plus 7 additional consistency issues (#1242-#1250). Issue #1230 (targeting_overlay semantics) was already resolved in a prior commit.

Original schema gaps (#1223-#1239)

Error handling (Error.code has no standardized vocabulary; agents cannot classify errors for autonomous recovery #1223): Error.recovery field (transient | correctable | terminal) + new error-code enum vocabulary
Idempotency (create_media_buy has no idempotency key; agent retries risk duplicate spend commitments #1224): idempotency_key on UpdateMediaBuyRequest, SyncCreativesRequest; documented buyer_ref dedup semantics on create
Media buy lifecycle (MediaBuyStatus missing 'rejected' state; post-creation rejection has no protocol representation #1225): rejected status + rejection_reason field on MediaBuy
Protocol version (Protocol version never sent on requests; sellers supporting v2+v3 simultaneously cannot dispatch correctly #1226): Document version negotiation via capabilities handshake; HTTP header is optional
Async polling (Async tasks have no polling guidance; agents without webhook infrastructure have no recovery path #1227): polling object moved to adcp section (protocol layer, applies to all domain protocols)
Package response (Package response type missing optimization_goals, catalog, and format_ids from PackageRequest #1229): Echo catalogs (array) and format_ids on Package
Signal deactivation (No deactivate_signal operation; activated segments persist indefinitely after campaign end #1231): action: activate | deactivate on ActivateSignalRequest
Signal metadata (GetSignalsResponse: categorical signals have no 'categories' field; buyers cannot construct valid targeting #1232): categories and range fields on signal entries
Property list filters (PropertyListFilters.countries_all and channels_any are required; global or all-channel lists are not representable #1233): Make countries_all and channels_any optional
Content standards response (UpdateContentStandardsResponse is not a discriminated union; inconsistent with all other write operations #1234): Replace flat object with success: true/false discriminated union
Product refinement (No standalone get_forecast task; iterative planning requires repeated get_products calls #1235): buying_mode discriminator with three modes (brief, wholesale, refine). Refine mode requires product_ids and/or proposal_id — sellers return updated forecasts, pricing, and configurations. PRODUCT_NOT_FOUND and PROPOSAL_EXPIRED error codes for agent recovery.
Creative assignments (SyncCreativesRequest.assignments map has ambiguous key direction and missing weight/placement fields #1237): Replace ambiguous map with typed array (breaking)
Batch preview (PreviewBatchResultSuccess and PreviewBatchResultError are empty shells; batch preview is non-functional #1238): Add required success/creative_id to results
Creative delivery pagination (GetCreativeDeliveryRequest uses offset pagination; inconsistent with protocol-wide cursor standard #1239): Replace limit/offset with PaginationRequest

Consistency fixes (#1242-#1250)

signals: account_id field should use AccountReference discriminated union #1242: Signals account_id: string → account: $ref account-ref.json (breaking)
activate-signal: deployments field should be named destinations for consistency #1244: ActivateSignalRequest.deployments → destinations (breaking)
get-creative-features: request missing account context for billing #1245: Add optional account to GetCreativeFeaturesRequest
schema: consent_basis should be a shared enum reference, not inline #1246: Extract consent_basis to enums/consent-basis.json
schema: Period/date-range type is duplicated inline across multiple schemas #1247: Extract core/date-range.json and core/datetime-range.json, replace 4 inline period objects
get-creative-features: endpoint name is ambiguous - consider rename to evaluate-creative or assess-creative #1248: Clarify get_creative_features description (evaluation semantics)
sync-audiences-request: errorMessage keyword is an ajv extension, not valid JSON Schema draft-07 #1250: Remove non-standard errorMessage keyword from sync-audiences-request

Additional refinements

Package.catalog → Package.catalogs (array) for multi-catalog packages (breaking)
PackageUpdate.catalog → PackageUpdate.catalogs (array) to match
Remove idempotency_key from CreateMediaBuyRequest (buyer_ref is the dedup key)
Soften x-adcp-version from MUST HTTP header to MAY
product_ids and proposal_id forbidden via false in brief/wholesale schema variants
PRODUCT_NOT_FOUND added to error-code enum (distinct from PRODUCT_UNAVAILABLE)
Filter-vs-brief precedence documented (filters are hard constraints on publisher curation)
reach optimization goal documented with reach_unit and target_frequency fields
account field added to sync-creatives-request embedded examples

Specification alignment

All RFC-style specification docs updated to match schema changes:

Error handling docs: recovery field, recovery-based categorization, RATE_LIMITED code
Media buy spec: rejected status, idempotency_key, buying_mode: refine with product/proposal refinement
Signals spec & task docs: account ref, destinations, action field, signal metadata
Property list spec & task docs: optional countries_all/channels_any filters
Task reference index: updated descriptions and workflow sections, fixed step numbering
Product discovery docs: "Iterating on Proposals" rewritten for explicit refine mode
get_products docs: all examples include buying_mode, refinement section with product/proposal/refresh examples
Optimization docs: reach metric added to metrics table and strategy guide

Split to separate PRs (per review)

get_adcp_capabilities missing: async behavior per task, proposal support flag, and operational limits #1228 capabilities completeness (async_tasks, supports_proposals, limits)
ProvidePerformanceFeedbackRequest is too vague to carry real measurement data #1236 performance feedback measurement extensions (metric_value, metric_unit, etc.)

Tracked for future work

Design: seller-generated creatives bundled with media proposals #1255 Seller-generated creatives design (catalog-to-creative bundling for platforms like Dynamic Ads)

Expert decisions (no change needed)

account-ref: add explicit discriminator field for type narrowing #1243: Keep AccountReference implicit discrimination (protocol expert: additionalProperties: false + zero field overlap makes it unambiguous)
signals: signal_agent_segment_id field name is redundant in request context #1249: Keep signal_agent_segment_id (protocol expert: name does real semantic work disambiguating from buyer-side segments)

Breaking changes

SyncCreativesRequest.assignments type changed from object to typed array
ActivateSignalRequest.deployments renamed to destinations
ActivateSignalRequest.account_id → account: AccountReference
GetSignalsRequest.account_id → account: AccountReference
Package.catalog → Package.catalogs (array)
PackageUpdate.catalog → PackageUpdate.catalogs (array)
buying_mode now required on get_products (was optional)
product_ids and proposal_id rejected in brief/wholesale modes

Changeset set to major.

Test plan

Closes #1223, #1224, #1225, #1226, #1227, #1229, #1231, #1232, #1233, #1234, #1235, #1237, #1238, #1239, #1242, #1244, #1245, #1246, #1247, #1248, #1250

🤖 Generated with Claude Code

Update specification and task reference docs to match schema changes from PR #1252: - Signals: deployments → destinations in request-side docs, add action and account fields to activate_signal and get_signals docs - Property governance: mark countries_all/channels_any as optional - Error handling: add recovery field, standard error codes from enums/error-code.json, update code examples to use recovery - Media buy: add get_forecast task reference page and spec section, document rejected status, add idempotency_key for mutations, fix conformance task count Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

dist/schemas/latest/media-buy/get-products-request.json

docs/building/implementation/error-handling.mdx

docs/media-buy/product-discovery/media-products.mdx

docs/media-buy/task-reference/get_products.mdx

docs/media-buy/specification.mdx

static/schemas/source/account/get-account-financials-response.json

docs/media-buy/task-reference/update_media_buy.mdx

github-actions · 2026-02-27T21:19:55Z

Schema Link Check Results

Commit: 3b38684 - fix: replace undocumented BILLING_MODEL_NOT_SUPPORTED error code

⚠️ Warnings (schema not yet released)

These schemas exist in source but haven't been released yet. The links will be broken until the next version is published:

https://adcontextprotocol.org/schemas/v1/media-buy/get-media-buy-delivery-request.json
- No releases found for version v1 yet
https://adcontextprotocol.org/schemas/v1/media-buy/get-media-buy-delivery-response.json
- No releases found for version v1 yet
https://adcontextprotocol.org/schemas/v2/media-buy/sync-audiences-request.json
- Schema exists in latest (source) but not yet released in v2
- Action: This link will work after next 2.x release is published
https://adcontextprotocol.org/schemas/v2/media-buy/sync-audiences-response.json
- Schema exists in latest (source) but not yet released in v2
- Action: This link will work after next 2.x release is published

To fix: Either:

Wait for the next release and merge this PR after the release is published
Use latest instead of a version alias if you need the link to work immediately (note: latest is the development version and may change)
Coordinate with maintainers to cut a new release before merging

…ation (#1223-#1239) Error handling: add `recovery` classification field to Error, new error-code enum vocabulary Idempotency: add `idempotency_key` to CreateMediaBuyRequest, UpdateMediaBuyRequest, SyncCreativesRequest Media buy lifecycle: add `rejected` status and `rejection_reason` to MediaBuy Protocol version: document x-adcp-version header requirement in capabilities response Async polling: add `polling` object to capabilities media_buy section Capabilities completeness: add `async_tasks`, `supports_proposals`, `limits` to capabilities Package response: echo `catalog` and `format_ids` back from create request Signal deactivation: add `action: activate | deactivate` to ActivateSignalRequest Signal metadata: add `categories` and `range` to signal entries in GetSignalsResponse Property list filters: make `countries_all` and `channels_any` optional Content standards response: replace flat object with success/error discriminated union Forecast task: new `get_forecast` task with GetForecastRequest and GetForecastResponse Performance feedback: add metric_value, metric_unit, measurement_provider, measurement_methodology, feedback_type; deprecate performance_index Creative assignments: replace ambiguous map with typed array including weight and placement_ids Batch preview: add required success/creative_id to results, fix errors array type Creative delivery pagination: replace limit/offset with standard PaginationRequest Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ssues PR review comments: - catalog → catalogs (array) on Package and PackageRequest (#comment-1) - Remove idempotency_key from CreateMediaBuyRequest; buyer_ref is the dedup key (#comment-3) - Soften x-adcp-version from MUST HTTP header to MAY; version via capabilities handshake (#comment-4) - Revert async_tasks, supports_proposals, limits from capabilities (split to separate PR) (#comment-5) - Revert metric_value/metric_unit/feedback_type from performance feedback (split to separate PR) (#comment-6) New issues: - #1242: signals account_id: string → account: $ref account-ref.json - #1244: activate-signal deployments → destinations - #1245: add optional account to get-creative-features-request - #1246: extract consent_basis to enums/consent-basis.json - #1247: extract date-range.json and datetime-range.json, replace inline periods - #1248: clarify get_creative_features description (evaluation, not discovery) - #1250: remove ajv-specific errorMessage from sync-audiences-request Expert decisions (no change): - #1243: keep AccountReference implicit discrimination (protocol expert) - #1249: keep signal_agent_segment_id (protocol expert) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Update specification and task reference docs to match schema changes from PR #1252: - Signals: deployments → destinations in request-side docs, add action and account fields to activate_signal and get_signals docs - Property governance: mark countries_all/channels_any as optional - Error handling: add recovery field, standard error codes from enums/error-code.json, update code examples to use recovery - Media buy: add get_forecast task reference page and spec section, document rejected status, add idempotency_key for mutations, fix conformance task count Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…rkflow Address review comment: explain why get_forecast operates on one product (parameters are product-specific), how to compare products (parallel calls), and that portfolio-level cross-product forecasting is out of scope. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Instead of a separate get_forecast task, extend get_products with a product_ids array for refreshing forecasts on known products. This keeps the iterative discovery workflow in-band — agents call get_products with a brief for discovery, then re-call with product_ids to refine budgets, dates, and targeting without re-discovering inventory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace the standalone product_ids approach with a proper buying_mode variant. buying_mode is now always required with three values: brief (curated discovery), wholesale (raw catalog), and refine (iterate on known products with updated forecasts, pricing, and packages). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Polling is a transport-level concern that applies to all async tasks across all domain protocols, not just media buys. Move it to adcp.polling alongside major_versions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Refine mode now accepts product_ids, proposal_id, or both. This lets agents iterate on a seller's proposed media plan — adjusting budgets, dates, and allocations — using the same refinement loop as individual products. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add PRODUCT_NOT_FOUND and PROPOSAL_EXPIRED error codes - Add refresh-only refine example (product_ids without brief) - Document combo semantics (product_ids + proposal_id) - Add notes on proposal lifecycle and product ID stability - Fix duplicate step numbering in Getting Started - Align media-products.mdx with refine mode patterns Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…y fields - Add PRODUCT_NOT_FOUND error code to enum (distinct from PRODUCT_UNAVAILABLE) - Forbid product_ids and proposal_id in brief/wholesale variants via `false` - Fix "package details" → "product configurations" in schema description - Clarify expires_at is optional on proposals - Clarify filter-vs-brief precedence in docs - Update doc: refine-only fields are rejected, not silently ignored - Remove stale .md files (Docusaurus → Mintlify migration artifacts) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Align PRODUCT_NOT_FOUND description with enum (were never valid, not no longer available) - Rename package-update.json catalog → catalogs array (matches package.json) - Add required account field to sync-creatives-request examples - Document reach optimization in optimization goals (schema already has it) - Add reach metric to metrics table and choosing-a-strategy table Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Fix RATE_LIMIT_EXCEEDED → RATE_LIMITED across 5 doc files (matches enum) - Add ACCOUNT_SETUP_REQUIRED and ACCOUNT_AMBIGUOUS to error-code enum - Add rejected to delivery response inline status enum (matches media-buy-status) - Remove TIMEOUT from isRetryable() example (not a domain error code) - Update index.json lastUpdated to 2026-02-27 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… review - media-products.mdx: formats → format_ids, add publisher_properties and delivery_measurement to field list, add publisher_properties to product examples - specification.mdx: add sync_audiences task (twelve → thirteen), add requirements - task-reference/index.mdx: add sync_audiences to overview table, response time categories, and workflow categories - update_media_buy.mdx: add catalogs, keyword_targets_add/remove, negative_keywords_add/remove to Package Update Object table - list-creatives-response.json: add missing delivery_type discriminator to VAST asset example Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Billing periods are calendar dates, but the buyer needs to know the seller's timezone to interpret where day boundaries fall. A seller billing in America/Los_Angeles and a buyer in America/New_York will see different spend for the same calendar date without this. Required field — sellers MUST return their billing timezone as an IANA timezone string alongside period, currency, and account. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Use UNSUPPORTED_FEATURE (already in error-code enum) in financials response example and docs error table. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

bokelley mentioned this pull request Feb 27, 2026

Design: seller-generated creatives bundled with media proposals #1255

Closed