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
Creative-format asset_type is a closed discriminated union — additive spec growth breaks all response consumers #742
ListCreativeFormatsResponse (and the underlying creative-format asset model) validates asset_type as a closed discriminated union of single-value Literals. Any AdCP-additive asset type that isn't in that frozen set makes the
entire response fail validation, even for the formats a client fully understands. AdCP enums grow additively by design, so this makes benign protocol evolution a breaking change for every response-consuming client.
Evidence (live, today)
The canonical reference agent https://creative.adcontextprotocol.org/mcp list_creative_formats returns 57 well-formed formats; several assets use asset_type: "pixel_tracker" (e.g. asset_id: "impression_tracker").
ListCreativeFormatsResponse.model_validate(payload) → 2700 ValidationErrors (literal_error ×2025 + discriminated-union missing ×675), all on formats[].assets[].asset_type. pixel_tracker is absent from both pinned 4.3.0 and
latest 5.4.0 — so this is not "upgrade to fix"; the structural trap persists in main.
Root cause (exact refs)
src/adcp/types/generated_poc/core/format.py:253–319 — asset_type: Literal['image']='image' … 'video' … 'webhook'; one closed single-value Literal per union arm, no open/unknown arm.
src/adcp/types/aliases.py:1199+ — discriminated union on asset_type over those generated arms; closed set {image,video,audio,text,markdown,html,css,javascript,vast,daast,url,webhook,…}.
A discriminated union of closed Literals fails every arm for an unrecognized discriminator → wholesale response rejection.
Impact
A single new asset type zeroes out the whole list_creative_formats catalog for the client, not just the new format. The official reference agent is currently un-consumable by any pinned adcp client. Forward compatibility is
expected precisely here — an additive change parties don't use shouldn't break them.
(a) Add an UnknownFormatAsset fallback arm (asset_type: str + raw passthrough) so unrecognized slots parse as typed-unknown instead of failing the union; or
(b) Model response-side asset_type as KnownAssetType | str (open enum); or
(c) A lenient response-parse mode that quarantines unparseable assets/formats into a structured unsupported/diagnostics field instead of raising.
Keep closed Literals on request/emit types (loud validation there is correct). Symmetric to the existing emit-side to_wire_dict seam (#602) — this is the missing read-side counterpart.
Acceptance
A list_creative_formats response containing a format with a novel asset_type parses successfully; known formats returned; unknown represented-as-unknown or excluded with diagnostics; no wholesale ValidationError. Regression test with a synthetic novel asset_type.
Classification: bug — read-path regression (P1: reference agent currently un-consumable by any pinned client)
Root cause confirmed.Format.assets and Assets94.assets in generated_poc/core/format.py use closed Pydantic discriminated unions — one Literal['image'] arm per known type, no fallback. An unrecognized asset_type triggers one ValidationError per arm per asset slot, resulting in ~2700 errors that zero out the entire list_creative_formats response. The pixel_tracker asset type present in the canonical reference agent at creative.adcontextprotocol.org hits this today.
Expert review: two independent reviews (protocol + code) found no blocking concerns. The Pydantic v2 callable Discriminator + Tag open union pattern is the spec-correct approach. Asymmetric strictness (Postel's Law) is preserved: emit-path request types keep closed Literal arms; parse-path response types get the open union with an UnknownFormatAsset fallback arm.
_forward_compat.py (new, preserved across codegen) — patches Format.assets and Assets94.assets at import time via model_rebuild(force=True)
13 new regression tests; 4324 total tests passing; ruff clean
Acceptance criteria from issue: ✅ list_creative_formats response with novel asset_type parses successfully; ✅ known formats returned intact; ✅ unknown represented as UnknownFormatAsset (structural fields validated, extra fields preserved in __pydantic_extra__); ✅ no wholesale ValidationError; ✅ regression test with synthetic novel asset type.
Activity
bokelley commentedon May 19, 2026
Triage
Classification: bug — read-path regression (P1: reference agent currently un-consumable by any pinned client)
Root cause confirmed.
Format.assetsandAssets94.assetsingenerated_poc/core/format.pyuse closed Pydantic discriminated unions — oneLiteral['image']arm per known type, no fallback. An unrecognizedasset_typetriggers oneValidationErrorper arm per asset slot, resulting in ~2700 errors that zero out the entirelist_creative_formatsresponse. Thepixel_trackerasset type present in the canonical reference agent atcreative.adcontextprotocol.orghits this today.Expert review: two independent reviews (protocol + code) found no blocking concerns. The Pydantic v2 callable
Discriminator+Tagopen union pattern is the spec-correct approach. Asymmetric strictness (Postel's Law) is preserved: emit-path request types keep closedLiteralarms; parse-path response types get the open union with anUnknownFormatAssetfallback arm.Draft PR opened: #744
Changes:
aliases.py—UnknownFormatAsset/UnknownGroupAssetfallback classes +FormatAssetUnion/GroupFormatAssetUnionopen discriminated unions_forward_compat.py(new, preserved across codegen) — patchesFormat.assetsandAssets94.assetsat import time viamodel_rebuild(force=True)Acceptance criteria from issue: ✅
list_creative_formatsresponse with novelasset_typeparses successfully; ✅ known formats returned intact; ✅ unknown represented asUnknownFormatAsset(structural fields validated, extra fields preserved in__pydantic_extra__); ✅ no wholesaleValidationError; ✅ regression test with synthetic novel asset type.Generated by Claude Code
fix(types): open Format.assets discriminated union with UnknownFormat…
test(forward-compat-assets): the open union was a widening, and the s…