Python SDK (adcp 3.10.0) schema drift: MediaBuyStatus, AggregatedTotals, UpdateMediaBuySuccess out of sync with v3 schemas

[tescoboy]

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	✓

[bokelley]

Triage

Classification: Bug
Bucket(s): handlers (no handlers label exists in this repo — noted as gap)
Status: drafting-pr
Milestone: (omitted — no target version indicated)

What the experts said:

• code-reviewer: No blockers. MEDIA_BUY_STATE_MACHINE fix is correct; pending_start and pending_creatives action sets are appropriate. Nit: is_terminal_status has same drift risk pattern; test could add negative sync_creatives assertion.
• dx-expert: No blockers. All stale references cleaned. SKILL.md update accurate. Nit: intent comment for absent sync_creatives in pending_start would help coding agents avoid regenerating it.

My take: Most of the drift you reported was already fixed in v4.0.0 — MediaBuyStatus now has pending_creatives/pending_start (no pending_activation), AggregatedTotals has completed_views and views, and UpdateMediaBuySuccessResponse references the corrected enum. One real residual bug remained: MEDIA_BUY_STATE_MACHINE in helpers.py still used the stale pending_activation key, causing valid_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_status returns [] for any unrecognized string.

---

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

---

Generated by Claude Code