Repository navigation
Python SDK (adcp 3.10.0) schema drift: MediaBuyStatus, AggregatedTotals, UpdateMediaBuySuccess out of sync with v3 schemas #288
Description
Summary
The adcp Python library (3.10.0) is auto-generated from a stale snapshot and is out of sync with the AdCP v3 JSON schemas at /schemas/3.0.1/. Extending SDK types via inheritance (per CLAUDE.md Pattern #1) does not guarantee spec compliance — implementations have to audit the live schemas separately and apply field-level overrides where the SDK lags.
This issue documents concrete drift discovered during a compliance pass, verified against the live schemas. Cross-posting from a downstream implementation repo.
Evidence
SDK version: adcp 3.10.0
Schema source: https://adcontextprotocol.org/schemas/v3/ ($id declares 3.0.1)
1. MediaBuyStatus: pending_activation → pending_start + missing pending_creatives
SDK emits pending_activation. Live schema (enums/media-buy-status.json):
"enum": ["pending_creatives", "pending_start", "active", "paused", "completed", "rejected", "canceled"]
pending_activation does not appear. pending_creatives (required when creatives are unapproved) is absent from the SDK entirely.
Workaround: Override MediaBuyDeliveryData.status as a Literal of spec values; translate internal pending_activation → pending_start at emission time. Add pending_creatives as an override.
Note: the delivery-item response also allows pending, failed, and reporting_delayed — these are delivery-level statuses distinct from the top-level media-buy-status.json enum and may need separate handling.
2. AggregatedTotals.video_completions → completed_views
SDK field: video_completions
Live schema (get-media-buy-delivery-response.json → aggregated_totals):
"completed_views": { "description": "Total audio/video completions across all media buys" }No video_completions key exists in the schema. The rename happened upstream; SDK still has the old name.
Workaround: Subclass overrides model_dump to rename video_completions → completed_views on serialization.
3. AggregatedTotals missing spec fields
Live schema lists these on aggregated_totals:
| Field | In SDK? |
|---|---|
impressions |
✓ |
spend |
✓ |
clicks |
✓ |
completed_views |
✗ (SDK has video_completions) |
views |
✗ |
conversions |
✓ |
conversion_value |
✓ |
roas |
✓ |
new_to_brand_rate |
✓ |
Activity
bokelley commentedon Apr 28, 2026
Triage
Classification: Bug
Bucket(s): handlers (no
handlerslabel exists in this repo — noted as gap)Status: drafting-pr
Milestone: (omitted — no target version indicated)
What the experts said:
MEDIA_BUY_STATE_MACHINEfix is correct;pending_startandpending_creativesaction sets are appropriate. Nit:is_terminal_statushas same drift risk pattern; test could add negative sync_creatives assertion.sync_creativesinpending_startwould help coding agents avoid regenerating it.My take: Most of the drift you reported was already fixed in v4.0.0 —
MediaBuyStatusnow haspending_creatives/pending_start(nopending_activation),AggregatedTotalshascompleted_viewsandviews, andUpdateMediaBuySuccessResponsereferences the corrected enum. One real residual bug remained:MEDIA_BUY_STATE_MACHINEinhelpers.pystill used the stalepending_activationkey, causingvalid_actions_for_status("pending_start")to return[]. PR #289 fixes that.Draft PR: #289 — updates state machine keys, docstring, tests, and SKILL.md webhook example.
Note: if your codebase has stored
"pending_activation"status values, map them to"pending_start"—valid_actions_for_statusreturns[]for any unrecognized string.Triaged by Claude Code. Session: https://claude.ai/code/session_01Q4gEoNmiYsfqnfFSR71JLg
Generated by Claude Code
fix(handlers): sync MEDIA_BUY_STATE_MACHINE with spec v3 enum (adcont…