Skip to content

bug(types): generated request models bind to sibling *Input classes, rejecting subclasses of the public exported type #1181

Closed

Description

@bokelley

Summary

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.

Current behavior

adcp/types/__init__.py exports TargetingOverlay.

Generated models bind elsewhere:

adcp/types/generated_poc/media_buy/package_update.py:144        targeting_input.TargetingOverlayInput | None
adcp/types/generated_poc/media_buy/package_request.py:220       targeting_input.TargetingOverlayInput | None
adcp/types/generated_poc/media_buy/package_control.py:46        targeting_input.TargetingOverlayInput | None
adcp/types/generated_poc/media_buy/product_purchase_input.py:38 targeting_input.TargetingOverlayInput | None

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:

from adcp.types import TargetingOverlay as LibraryTargetingOverlay

class TargetingOverlay(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.

Activity

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

    @bokelley
    ContributorAuthor

    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:

    • 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 union TargetingOverlay | 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.


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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 16, 2026
  4. bokelley commented on Sep 16, 2026

    @bokelley
    ContributorAuthor

    Another instance of the same root cause, in the opposite direction — the public export is laxer than the generated model and the schema:

    adcp.types.CreativeAsset            (adcp.types.canonical_creative)
      format_kind: CanonicalFormatKind | str
    
    generated_poc.core.creative_asset.CreativeAsset
      format_kind: CanonicalFormatKind | None
    

    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:

    >>> from adcp.types import CreativeAsset
    >>> CreativeAsset.model_validate(
    ...     {"creative_id": "c1", "name": "n", "assets": {}, "format_kind": "totally_bogus"}
    ... ).format_kind
    'totally_bogus'

    A seller validating inbound creatives therefore has to re-enforce the SDK's own enum:

    @field_validator("format_kind", mode="before")
    @classmethod
    def require_canonical_format_kind(cls, value): return CanonicalFormatKind(value)

    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.

  5. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 16, 2026
  6. bokelley commented on Sep 16, 2026

    @bokelley
    ContributorAuthor

    Triage update

    Re: CreativeAsset.format_kind: CanonicalFormatKind | str

    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.


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


    Generated by Claude Code

  7. removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 16, 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