Skip to content

bug(types): exported CreativeAsset still widens format_kind to CanonicalFormatKind | str #1241

Closed

Description

@bokelley

Summary

#1190 fixed the targeting-input half of #1181. The other case recorded on that issue is still present in 8.0.0b18:

>>> from adcp.types import CreativeAsset
>>> CreativeAsset.model_fields["format_kind"].annotation
CanonicalFormatKind | str
>>> CreativeAsset.model_validate(
...     {"creative_id": "c1", "name": "n", "assets": {}, "format_kind": "totally_bogus"}
... ).format_kind
'totally_bogus'

core/canonical_format_kind.json is a closed enum, and the generated generated_poc.core.creative_asset.CreativeAsset types the field as CanonicalFormatKind | None. The exported type is laxer than the schema it implements, so sellers validating inbound creatives must re-enforce the SDK's own enum:

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

If the | str widening is intentional forward compatibility, it would help to mark which enums are open in the schema and generate leniency only for those.

Refs #1181, #1190.

Activity

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

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): validation, client (neither label exists in this repo — flagging the gap)
    Status: ready-for-human
    Milestone: (omitted — no target version signalled)

    Root cause confirmed. canonical_creative.py lines 588–592 and 594–598 override format_kind on the exported CreativeAsset and Creative with _OpenCanonicalFormatKind (CanonicalFormatKind | str, union_mode="left_to_right"). The generated wire model (generated_poc.core.creative_asset.CreativeAsset) types it as the closed CanonicalFormatKind | None, so the canonical override is strictly laxer than the schema it wraps.

    What the experts said:

    • code-analysis: The _OpenCanonicalFormatKind type is defined locally in canonical_creative.py (line 122–125) and was intentionally mirrored from _forward_compat.py, which applies the same open union to CreativeManifest.format_kind and DeliveryCreative.format_kind under the explicit rationale "Canonical format kinds are an open enum on consumer boundaries." The Format class in the same file uses strict CanonicalFormatKind, confirming this was a conscious asymmetry.
    • protocol-analysis: The open-union rationale in _forward_compat.py is targeted at response models where a seller SDK at an older spec version receives a format_kind value introduced by a newer revision. CreativeAsset is used in request models (SyncCreativesRequest, PackageRequest) where the buyer is producing the creative — a stricter validation boundary than a received response. Whether CreativeAsset should be treated as a "consumer boundary" (open) or a "producer boundary" (closed) is a design decision, not derivable from the code alone.

    My take: The bug is real — a closed-enum field accepting "totally_bogus" is wrong and forces sellers to add a re-validation step the SDK should handle. The fix is clear (swap _OpenCanonicalFormatKind for CanonicalFormatKind on CreativeAsset and Creative in canonical_creative.py). However, this is a breaking runtime change: code passing non-canonical strings as format_kind (e.g., forward-probing a newer spec value before upgrading the SDK) would now get a ValidationError. This needs an explicit decision from a maintainer on whether CreativeAsset counts as a consumer boundary.

    Implementation brief (once authorized):

    • In src/adcp/types/canonical_creative.py, change line 591 override from (_OpenCanonicalFormatKind, Field()) to (CanonicalFormatKind, Field()) and line 597 from (_OpenCanonicalFormatKind, Field()) to (CanonicalFormatKind, Field()).
    • Also verify _CreativeManifestBase (line 600–609): its _OpenCanonicalFormatKind | None was patched separately in _forward_compat.py for the wire model and may be intentional (response boundary) — do not change without a separate decision.
    • Add regression tests: CreativeAsset.model_validate({..., "format_kind": "totally_bogus"}) must raise ValidationError; valid enum values must still coerce correctly.
    • Run mypy src/ and pytest tests/ on the change; the ergonomic coerce_to_enum validators in _ergonomic.py do not cover canonical_creative models, so no coercion patch is needed.

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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Sep 28, 2026
  4. added 2 commits that reference this issue on Sep 29, 2026
    2765ef0
    b10d530
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