Repository navigation
Description
Problem
SDK 8.0.0b2 advertises support for AdCP 3.0, 3.1, and 3.2 beta, and its runtime JSON Schema validation correctly selects a bundle from the request's adcp_version. The public Pydantic type surface and MCP tools/list schemas, however, are generated only from the compile-time 3.2 schema.
That lets an integration pinned to 3.1 construct or advertise 3.2 semantics accidentally.
Reproduction
Two concrete wire deltas in the released wheel:
ListCreativesRequestexposes 3.2-only fields globally:
from adcp.types import ListCreativesRequest
assert "assignment_projection" in ListCreativesRequest.model_fields
assert "assignment_limit" in ListCreativesRequest.model_fieldsThe bundled 3.1 schema has neither property; the 3.2 beta schema has both.
PackageRequest.budgetis optional in the public model:
from adcp.types import PackageRequest
assert not PackageRequest.model_fields["budget"].is_required()The bundled 3.1 schema requires product_id, budget, and pricing_option_id. The 3.2 beta schema requires only product_id and pricing_option_id, because seller-optimized allocation permits omitted package budgets.
The same mismatch reaches server discovery: adcp.server.mcp_tools builds one process-global ADCP_TOOL_DEFINITIONS schema set from the current public Pydantic models. A server that claims 3.1 compatibility can therefore advertise 3.2-only input semantics even though dispatch later validates an explicit 3.1 request against the correct 3.1 JSON Schema bundle.
Impact
- A 3.1 buyer gets no type-checking signal when it constructs a request that only 3.2 accepts.
- A 3.1 seller can type its handler with a model that accepts 3.2-only fields or makes a 3.1-required field optional.
- MCP clients generate requests from
tools/list; version-aware runtime rejection happens too late and contradicts discovery. - The SDK's compatibility claim is stronger than the safety offered by its primary public types.
Required before SDK 8 stable
Provide a supported version-scoped public surface, for example adcp.types.v31 / adcp.types.v32, version-bound model factories, or another stable namespace that does not expose generated_poc. The exact API is open, but it should satisfy:
- 3.1 public request/response models preserve 3.1 requiredness and fields.
- 3.2 public request/response models preserve 3.2 requiredness and fields.
- A version-pinned client/server can select the matching public model surface without private imports.
- MCP tool schemas reflect the server/session's selected release, or the SDK documents and enforces that one server instance has only one discoverable native release.
- Tests cover at least the
ListCreativesRequestandPackageRequest.budgetdeltas above across 3.1 and 3.2. - The migration guide explains what unversioned
adcp.typesmeans (latest/native vs negotiated) and when adopters must use a versioned surface.
If version-scoped public models cannot land before stable 8, narrow the compatibility documentation: runtime wire validation is multi-version, but the public type/tool-schema surface is latest-schema-only and is unsafe as a source of truth for older negotiated releases.
Activity
bokelley commentedon Aug 18, 2026
Triage
Classification: Bug
Bucket(s): client, validation (note: neither label exists in this repo — flagging gap for maintainers)
Status: ready-for-human
Milestone: omitted (no milestone named)
What the experts said:
PackageRequest.budgetoptional/required inversion and the process-global MCPtools/listmismatch are protocol conformance violations, not just type-safety concerns. The budget issue is more dangerous becauseextra='allow'means a 3.1 seller silently accepts an under-specified buy. Recommends filteringtools/listinputSchema via the existingschema_loader.get_validatorpath (same technique as_widen_media_buy_output_schema_for_legacy_statuses) rather than parallel Pydantic namespaces — cheaper and avoids codegen churn.adcp.types.v31/v32namespaces are additive but carry 5-8 days of plumbing plus ongoing codegen maintenance (two parallel generated trees risk the CLAUDE.md variant-numbering churn). Thebudgetbug is a real correctness issue, not a doc gap. Recommends separating the two problems: fix the bug first, decide the namespace architecture separately.My take: This bundles two distinct problems — a concrete field-requiredness bug (
PackageRequest.budget) and a broader architectural question (version-scoped public type surface). The schema-filter approach for MCP schemas is a faster path to 3.1 conformance than parallel Pydantic namespaces; @bokelley should confirm whether that approach satisfies the stable-8 bar or whether full versioned namespaces are required. Flagging for design direction before any implementation brief is written.Triaged by Claude Code. Session: https://claude.ai/code/session_01S5QFhUajUzjmSL2JiSBbiL
Generated by Claude Code