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): exported CreativeAsset still widens format_kind to CanonicalFormatKind | str #1241
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:
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.
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.
Activity
bokelley commentedon Sep 28, 2026
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.pylines 588–592 and 594–598 overrideformat_kindon the exportedCreativeAssetandCreativewith_OpenCanonicalFormatKind(CanonicalFormatKind | str,union_mode="left_to_right"). The generated wire model (generated_poc.core.creative_asset.CreativeAsset) types it as the closedCanonicalFormatKind | None, so the canonical override is strictly laxer than the schema it wraps.What the experts said:
_OpenCanonicalFormatKindtype is defined locally incanonical_creative.py(line 122–125) and was intentionally mirrored from_forward_compat.py, which applies the same open union toCreativeManifest.format_kindandDeliveryCreative.format_kindunder the explicit rationale "Canonical format kinds are an open enum on consumer boundaries." TheFormatclass in the same file uses strictCanonicalFormatKind, confirming this was a conscious asymmetry._forward_compat.pyis targeted at response models where a seller SDK at an older spec version receives aformat_kindvalue introduced by a newer revision.CreativeAssetis used in request models (SyncCreativesRequest,PackageRequest) where the buyer is producing the creative — a stricter validation boundary than a received response. WhetherCreativeAssetshould 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_OpenCanonicalFormatKindforCanonicalFormatKindonCreativeAssetandCreativeincanonical_creative.py). However, this is a breaking runtime change: code passing non-canonical strings asformat_kind(e.g., forward-probing a newer spec value before upgrading the SDK) would now get aValidationError. This needs an explicit decision from a maintainer on whetherCreativeAssetcounts as a consumer boundary.Implementation brief (once authorized):
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())._CreativeManifestBase(line 600–609): its_OpenCanonicalFormatKind | Nonewas patched separately in_forward_compat.pyfor the wire model and may be intentional (response boundary) — do not change without a separate decision.CreativeAsset.model_validate({..., "format_kind": "totally_bogus"})must raiseValidationError; valid enum values must still coerce correctly.mypy src/andpytest tests/on the change; the ergonomiccoerce_to_enumvalidators in_ergonomic.pydo not covercanonical_creativemodels, so no coercion patch is needed.Triaged by Claude Code. Session: https://claude.ai/code/session_01EqUHRPPXriFSD6hGdsEMr8
Generated by Claude Code
fix(types)!: enforce closed creative format kinds
fix(types): tolerate manifests across buyer responses
fix(types): stop a tolerant delivery model passing as its strict wire…
refactor(codegen)!: make the generated domain tree the one public typ…
fix(types): bind the delivery readback manifest to the manifest root,…