Repository navigation
Description
Problem
#1048 adds valuable generated .pyi stubs for version-scoped models, but it
intentionally leaves their runtime implementation as
RootModel[dict[str, Any]]. The module documentation explicitly says that
subclassing to add Pydantic fields is unsupported and recommends composing
adopter state beside the boundary model.
That leaves the extension half of #1046 unresolved for seller frameworks whose
public schemas extend SDK schemas with excluded internal fields:
from adcp.types.v31 import ListCreativesRequest
from pydantic import Field
class SellerListCreativesRequest(ListCreativesRequest):
internal_tenant_id: str = Field(exclude=True)On 8.0.0b4 (and with #1048's unchanged RootModel runtime), class definition
fails with:
NameError: Unexpected field with name 'internal_tenant_id'; only 'root' is
allowed as a field of a RootModel
Static stubs make direct construction and attribute access pleasant for type
checkers, but they do not provide runtime Pydantic fields or nested Pydantic
models. Composition beside the boundary object does not replace an extension
model at transport/business-logic boundaries where one validated model must
carry both protocol and excluded internal state.
The practical result for a 3.1 seller is that it must still inherit the
unversioned 3.2-generated classes and patch the version delta locally. Our SDK
8 migration currently has to:
- remove
assignment_projectionandassignment_limitduring 3.1
ListCreativesRequestserialization; and - add a validator restoring the 3.1-required
PackageRequest.budget.
That is exactly the semantic drift the version-scoped surface should let an
adopter avoid.
Requested extension surface
Please provide a supported way to define a normal Pydantic model that extends
one pinned protocol version. Full isolated per-version runtime codegen is one
valid implementation, but the API shape is open.
Acceptance criteria:
- An adopter can add an
exclude=Trueinternal field to a 3.1 request or
response without converting through an untyped root dictionary. - Protocol fields appear in runtime
model_fields, not only in.pyi. - Nested protocol objects retain typed Pydantic runtime values where the
normal generated surface provides them. - The extended model emits the pinned version's JSON Schema and wire shape;
excluded adopter fields never serialize. - The 3.1 extension does not admit 3.2-only creative assignment fields and
keeps package budget required. - The solution has a stable public import/factory path and does not require
generated_pocimports.
Relationship to #1046 and #1048
This is the explicitly deferred runtime-extension portion of #1046. The stubs
in #1048 are useful and should remain; this asks for the complementary runtime
Pydantic extension seam needed by schema-extending adopters.
Activity
bokelley commentedon Aug 19, 2026
Triage
Classification: Feature request
Bucket(s): client (types surface —
src/adcp/types/versioned.py; no matching repo label for this bucket)Status: ready-to-implement
What the experts said:
pydantic.create_model()not baretype()for theBaseModelsubclass; criterion 3 (nested typed runtime models) requires explicit depth scoping before implementation.make_versioned_base("3.1", "ListCreativesRequest")) is the clear ergonomic winner; recommend scoping criterion 3 to top-level fields for v1 to ship a useful feature without runtime surprises, with fully-recursive nested models as a follow-up.My take: Both experts agree this is well-scoped and non-breaking — a factory that produces a real
BaseModelsubclass with bundled-schema validation and a canonicalmodel_json_schema()override, alongside the existingVersionedSchemaModelsurface. One clarification is needed before implementation: does criterion 3 ("nested protocol objects retain typed Pydantic runtime values") mean top-level fields only, or fully recursive nested model generation?Implementation scope:
make_versioned_base(version: str, model_name: str) -> type[BaseModel]tosrc/adcp/types/versioned.pyusingpydantic.create_model(), drawing fields from_object_shapes(), adding amodel_validatorthat runs the bundled JSON Schema check, and overridingmodel_json_schema()/__get_pydantic_json_schema__to return the canonical bundled schema.adcp.types.versionedpublic API (criterion 6); nogenerated_pocimports needed.Field(exclude=True)subclassing,model_fieldsagainst a known 3.1/3.2 delta field,model_json_schema()round-trip, and confirm 3.1 rejectsassignment_projection/assignment_limit.schema_model_for_version/VersionedSchemaModelsurface left unchanged.Triaged by Claude Code.
Generated by Claude Code