CreateMediaBuyResponse1 incorrectly declares buyer_ref (not in AdCP 3.x schema since GA)

[KonstantinMirin]

Problem

adcp.types.generated_poc.media_buy.create_media_buy_response.CreateMediaBuyResponse1 declares a buyer_ref: str | None = None field, but buyer_ref does not exist in the AdCP create-media-buy-response.json schema.

Verified against:

• v3.1.0-beta.3 — grep buyer_ref returns empty
• v3.1.0-rc.8 — grep buyer_ref returns empty

The field was present in a pre-3.0 release candidate but was removed before 3.0 GA. The SDK codegen is carrying it forward from a historical schema version.

Generated source

# generated by datamodel-codegen:
#   filename:  media_buy/create_media_buy_response.json
#   timestamp: 2026-05-22T13:15:12+00:00

class CreateMediaBuyResponse1(AdcpVersionEnvelope):
    model_config = ConfigDict(extra='allow')
    media_buy_id: str
    packages: list[package_1.Package]
    buyer_ref: str | None = None          # ← NOT IN SCHEMA
    media_buy_status: ...
    status: ...

Impact

Tests that assert buyer_ref not in model_fields fail on SDK 5.7 because the field exists on the class. The field is never populated by spec-compliant sellers, but its presence confuses schema validation and contract tests.

Expected

Remove buyer_ref from CreateMediaBuyResponse1. It should only appear on the request schema.

[bokelley]

Triage

Classification: Bug
Bucket(s): client (no matching repo label for client or validation — flagged in triage summary)
Status: ready-for-human
Milestone: (omit — no target version signaled)

What the experts said:

• code-reviewer: Technically breaking — tests assert success.buyer_ref == "ref_456" (test_discriminated_unions.py:170, 332; test_public_api.py:278), the server/responses.py:media_buy_response() helper actively injects buyer_ref into response dicts (lines 396, 441–442), and update_media_buy_response.py:33 carries the same stale field; removal requires coordinated updates to ≥6 test files plus the server helper; surgical edit preferred over regeneration (the file already has hand-written validators that a re-run would clobber, and re-gen triggers 600+ line numbering churn per CLAUDE.md).
• dx-expert: Breaking under semver; MIGRATION_v1_to_v2.md actively teaches response.buyer_ref (lines 167, 179, 209), so adopters who followed the guide will get AttributeError; media_buy_response() buyer_ref kwarg also needs a parallel deprecation or it becomes a silent footgun (value accepted, falls into __pydantic_extra__ on parsed response); recommends deprecation-then-remove over clean removal, minor version bump.

My take: The diagnosis is unambiguous — buyer_ref is a pre-GA leftover that was never in the 3.x spec — but the blast radius is wider than a one-liner: the server-side helper and first-party migration docs both teach this field, so a clean removal needs a deprecation cycle decision and coordinated multi-file PR. Flagging for @bokelley to confirm approach (deprecate-now-remove-next-minor vs. clean removal with migration note).

Implementation scope when authorized:

• Remove buyer_ref: str | None = None from CreateMediaBuyResponse1 in src/adcp/types/generated_poc/media_buy/create_media_buy_response.py (line 30) — surgical edit, not regeneration
• Same removal from src/adcp/types/generated_poc/media_buy/update_media_buy_response.py (line 33) — same stale field
• Deprecate or remove buyer_ref kwarg from src/adcp/server/responses.py:media_buy_response() (lines 396, 441–442) — keeping kwarg without typed field silently drops the value into __pydantic_extra__
• Update tests: tests/test_discriminated_unions.py (lines 170, 332), tests/test_public_api.py (line 278), tests/test_response_str.py (lines 119, 128), tests/test_type_coercion.py (lines 166, 233, 281, 292, 429, 458), tests/test_server_dx.py (lines 146–148)
• Update MIGRATION_v1_to_v2.md (lines 167, 179, 209) to remove the response.buyer_ref example
• Decision needed: deprecation cycle (preferred for clean semver) vs. clean removal in current cycle

---

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

---

Generated by Claude Code