Skip to content

types: version-scope public models and MCP schemas for negotiated releases #1036

Closed

Description

@bokelley

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:

  1. ListCreativesRequest exposes 3.2-only fields globally:
from adcp.types import ListCreativesRequest

assert "assignment_projection" in ListCreativesRequest.model_fields
assert "assignment_limit" in ListCreativesRequest.model_fields

The bundled 3.1 schema has neither property; the 3.2 beta schema has both.

  1. PackageRequest.budget is 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 ListCreativesRequest and PackageRequest.budget deltas above across 3.1 and 3.2.
  • The migration guide explains what unversioned adcp.types means (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

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 18, 2026
  2. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 18, 2026
  3. bokelley commented on Aug 18, 2026

    @bokelley
    ContributorAuthor

    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:

    • ad-tech-protocol-expert: Both the PackageRequest.budget optional/required inversion and the process-global MCP tools/list mismatch are protocol conformance violations, not just type-safety concerns. The budget issue is more dangerous because extra='allow' means a 3.1 seller silently accepts an under-specified buy. Recommends filtering tools/list inputSchema via the existing schema_loader.get_validator path (same technique as _widen_media_buy_output_schema_for_legacy_statuses) rather than parallel Pydantic namespaces — cheaper and avoids codegen churn.
    • dx-expert: Full adcp.types.v31/v32 namespaces are additive but carry 5-8 days of plumbing plus ongoing codegen maintenance (two parallel generated trees risk the CLAUDE.md variant-numbering churn). The budget bug 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

  4. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions