You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
bug(types): generated request models bind to sibling *Input classes, rejecting subclasses of the public exported type #1181
In 8.0.0-beta.15, adcp.types exports TargetingOverlay as the public type, but every generated request model annotates the corresponding field as TargetingOverlayInput — a structurally similar sibling class with no inheritance relationship to the exported one. An application that extends the public type, as the SDK's own extension guidance directs, finds its instances rejected at those fields.
TargetingOverlayInput (generated_poc/core/targeting_input.py:42) does not inherit from TargetingOverlay. A subclass of the public type is not a subclass of the generated one, so Pydantic rejects it at those fields.
Why this defeats the documented extension pattern
The supported way to carry application-internal fields is to subclass the exported type:
fromadcp.typesimportTargetingOverlayasLibraryTargetingOverlayclassTargetingOverlay(LibraryTargetingOverlay):
"""Extends the AdCP overlay with internal dimensions."""
That subclass is a valid TargetingOverlay and an invalid TargetingOverlayInput. The only remedies available to an adopter are both bad: redeclare the field on every containing model to re-widen the annotation, or inherit from both classes so the instance satisfies each. Neither is discoverable, and both break again whenever codegen changes the sibling.
This is not specific to targeting — it is a general consequence of request models binding to *Input siblings rather than to the exported public type.
Required behavior
Generated request models should annotate fields with the same class the package exports, so that any subclass of the public type is accepted wherever that type is accepted.
If input and output shapes must genuinely differ, the input variant should inherit from the public type rather than parallel it, preserving substitutability in the direction adopters actually extend.
Acceptance criteria
isinstance(x, adcp.types.TargetingOverlay) implies x validates at every generated field that accepts an overlay.
A subclass of any exported type validates wherever that type is accepted, with no field redeclaration and no multiple inheritance.
The rule holds across the *Input family generally, not only for targeting.
A test constructs a trivial subclass of an exported type and round-trips it through a containing request model.
Extension guidance documents the guarantee.
Adopter impact
Embedded Sales Agent extends TargetingOverlay with internal dimensions per the documented pattern. On beta.15 we had to redeclare targeting_overlay on our PackageUpdate subclass purely to re-widen the annotation, with a comment explaining that the generated model points at a sibling class. Any adopter extending any exported type will hit the same wall at whichever field binds to that type's *Input sibling.
Classification: Bug Bucket(s): types (no matching repo label found for this bucket) Status: ready-to-implement Milestone: omitted — no target version named in issue
What the experts said:
code-reviewer: Bug confirmed. Critical nuance:TargetingOverlayInput and TargetingOverlay have the same field names but incompatible field types — geo/audience/device fields in TargetingOverlayInput use named RootModel wrappers (GeoCountries, AudienceInclude, etc.) while TargetingOverlay holds unwrapped raw types. Naively replacing the annotation would silently discard validation constraints (including a deprecation on axe_include_segment) and can produce serialization failures. The correct fix is a unionTargetingOverlay | TargetingOverlayInput | None at each of the four sites — this is non-breaking (strictly wider), preserves all existing callers, and makes subclasses of the public type valid. The existing _forward_compat.py patching infrastructure is exactly the right tool.
dx-expert: (analysis still arriving; core DX framing — adopters see TargetingOverlayInput in Pydantic error messages with no connection to the exported TargetingOverlay, and the extension guidance promises something the type system silently breaks — aligns with code-reviewer's confirmed blocker)
My take: The issue is scoped to exactly four field sites and one import-time patch in _forward_compat.py. The fix is non-breaking and all acceptance criteria in the issue are achievable without touching generated files. TargetingOverlayInput is also not currently exported from adcp.types, which should be remedied alongside the patch so adopters who reference it by its internal path have a stable import target.
Implementation scope:
src/adcp/types/_forward_compat.py — add four _patch_model_field calls (one per affected model) replacing targeting_overlay annotation from TargetingOverlayInput | None to TargetingOverlay | TargetingOverlayInput | None; add drift-assertion (verify TargetingOverlayInput is present in the current annotation before patching, matching the _patch_equivalent_model_field pattern); call model_rebuild(force=True) on each model.
src/adcp/types/_generated.py + _eager.py + __init__.py — export TargetingOverlayInput on the public surface so adopters have a stable import (from adcp.types import TargetingOverlayInput).
tests/ — add a test that subclasses adcp.types.TargetingOverlay, instantiates it, and constructs each of the four affected request models (PackageUpdate, PackageRequest, PackageControl, ProductPurchaseInput) with the subclass instance; assert Pydantic validation passes.
docs/ or extension guidance — document the guarantee: any subclass of an exported type validates wherever that type is accepted (no field redeclaration, no multiple inheritance required).
Required checks before merging:pytest tests/ (subset covering the new test), mypy src/, ruff check . / black --check ..
Non-breaking rationale: The union TargetingOverlay | TargetingOverlayInput | None is strictly wider than TargetingOverlayInput | None. No existing call site is affected. Adding a new export (TargetingOverlayInput) is additive. No generated files under generated_poc/ need touching.
core/canonical_format_kind.json is a closed enum, and unlike fields that document themselves as open for forward compatibility (buyer_reason.code, for example), nothing marks this one as extensible. But the public type's | str widening accepts anything:
Same underlying problem as the *Input siblings: the class the package exports is not the class that carries the schema contract, so adopters cannot rely on the exported type to mean what the schema says. Whichever direction the divergence runs — narrower (rejects valid subclasses) or wider (accepts invalid values) — the fix is one authoritative public type per schema type.
If the | str widening is deliberate forward-compatibility, it would help to mark which enums are open in the schema and generate leniency only for those, so closed enums keep their guarantee.
The | str widening is intentional, not a bug in the same class as the *Input sibling binding. _forward_compat.py lines 116–118 document the rationale explicitly:
Canonical format kinds are an open enum on consumer boundaries. Preserve values introduced by a newer protocol revision instead of rejecting the entire creative manifest. Known values still coerce to the StrEnum arm.
union_mode="left_to_right" means known values still parse as CanonicalFormatKind; unknown strings pass through rather than raise ValidationError. Same pattern OpenRTB uses for extensible int lists.
One valid secondary concern:CreativeAsset appears in both inbound (ListCreativesResponse) and outbound (SyncCreativesRequest, PackageRequest, PackageUpdate) contexts. The single-model design means the SDK won't reject a typo'd format_kind before it hits the wire on outbound. That's a real DX gap, but it's separate from #1181 — worth a dedicated issue.
Your schema-annotation idea (mark x-adcp-open-enum in the schema, generate widening only for marked enums) is architecturally correct and the right long-term fix. That's a 3-layer change (schema repo → codegen → SDK) and belongs in its own issue, not in this bug fix.
Status unchanged: ready-to-implement on the original *Input sibling brief.
Activity
bokelley commentedon Sep 16, 2026
Triage
Classification: Bug
Bucket(s): types (no matching repo label found for this bucket)
Status: ready-to-implement
Milestone: omitted — no target version named in issue
What the experts said:
TargetingOverlayInputandTargetingOverlayhave the same field names but incompatible field types — geo/audience/device fields inTargetingOverlayInputuse namedRootModelwrappers (GeoCountries,AudienceInclude, etc.) whileTargetingOverlayholds unwrapped raw types. Naively replacing the annotation would silently discard validation constraints (including a deprecation onaxe_include_segment) and can produce serialization failures. The correct fix is a unionTargetingOverlay | TargetingOverlayInput | Noneat each of the four sites — this is non-breaking (strictly wider), preserves all existing callers, and makes subclasses of the public type valid. The existing_forward_compat.pypatching infrastructure is exactly the right tool.TargetingOverlayInputin Pydantic error messages with no connection to the exportedTargetingOverlay, and the extension guidance promises something the type system silently breaks — aligns with code-reviewer's confirmed blocker)My take: The issue is scoped to exactly four field sites and one import-time patch in
_forward_compat.py. The fix is non-breaking and all acceptance criteria in the issue are achievable without touching generated files.TargetingOverlayInputis also not currently exported fromadcp.types, which should be remedied alongside the patch so adopters who reference it by its internal path have a stable import target.Implementation scope:
src/adcp/types/_forward_compat.py— add four_patch_model_fieldcalls (one per affected model) replacingtargeting_overlayannotation fromTargetingOverlayInput | NonetoTargetingOverlay | TargetingOverlayInput | None; add drift-assertion (verifyTargetingOverlayInputis present in the current annotation before patching, matching the_patch_equivalent_model_fieldpattern); callmodel_rebuild(force=True)on each model.src/adcp/types/_generated.py+_eager.py+__init__.py— exportTargetingOverlayInputon the public surface so adopters have a stable import (from adcp.types import TargetingOverlayInput).tests/— add a test that subclassesadcp.types.TargetingOverlay, instantiates it, and constructs each of the four affected request models (PackageUpdate,PackageRequest,PackageControl,ProductPurchaseInput) with the subclass instance; assert Pydantic validation passes.docs/or extension guidance — document the guarantee: any subclass of an exported type validates wherever that type is accepted (no field redeclaration, no multiple inheritance required).Required checks before merging:
pytest tests/(subset covering the new test),mypy src/,ruff check ./black --check ..Non-breaking rationale: The union
TargetingOverlay | TargetingOverlayInput | Noneis strictly wider thanTargetingOverlayInput | None. No existing call site is affected. Adding a new export (TargetingOverlayInput) is additive. No generated files undergenerated_poc/need touching.Triaged by Claude Code. Session: https://claude.ai/code/session_01HV6ZoC2BiV39FD6SW1QqF6
Generated by Claude Code
bokelley commentedon Sep 16, 2026
Another instance of the same root cause, in the opposite direction — the public export is laxer than the generated model and the schema:
core/canonical_format_kind.jsonis a closed enum, and unlike fields that document themselves as open for forward compatibility (buyer_reason.code, for example), nothing marks this one as extensible. But the public type's| strwidening accepts anything:A seller validating inbound creatives therefore has to re-enforce the SDK's own enum:
Same underlying problem as the
*Inputsiblings: the class the package exports is not the class that carries the schema contract, so adopters cannot rely on the exported type to mean what the schema says. Whichever direction the divergence runs — narrower (rejects valid subclasses) or wider (accepts invalid values) — the fix is one authoritative public type per schema type.If the
| strwidening is deliberate forward-compatibility, it would help to mark which enums are open in the schema and generate leniency only for those, so closed enums keep their guarantee.bokelley commentedon Sep 16, 2026
Triage update
Re:
CreativeAsset.format_kind: CanonicalFormatKind | strThe
| strwidening is intentional, not a bug in the same class as the*Inputsibling binding._forward_compat.pylines 116–118 document the rationale explicitly:union_mode="left_to_right"means known values still parse asCanonicalFormatKind; unknown strings pass through rather than raiseValidationError. Same pattern OpenRTB uses for extensible int lists.One valid secondary concern:
CreativeAssetappears in both inbound (ListCreativesResponse) and outbound (SyncCreativesRequest,PackageRequest,PackageUpdate) contexts. The single-model design means the SDK won't reject a typo'dformat_kindbefore it hits the wire on outbound. That's a real DX gap, but it's separate from #1181 — worth a dedicated issue.Your schema-annotation idea (mark
x-adcp-open-enumin the schema, generate widening only for marked enums) is architecturally correct and the right long-term fix. That's a 3-layer change (schema repo → codegen → SDK) and belongs in its own issue, not in this bug fix.Status unchanged: ready-to-implement on the original
*Inputsibling brief.Triaged by Claude Code. Session: https://claude.ai/code/session_01XfGVRcN2BMXZsk9sJ7XiQ5
Generated by Claude Code
fix(codegen)!: resolve structural pointer refs to the type they select (