Closed
Labels
Description
Context
While validating bokelley/salesagent#631 end-to-end, we found that legacy creative format IDs are upgraded by the SDK/schema layer, but implementations still need a reliable way to compare upgraded legacy IDs with structured canonical format refs.
Example failure mode:
- client sends legacy
display_300x250 - SDK/model validation upgrades this to canonical
display_imagewith width/height - implementation code still compares exact
(agent_url, id)tuples display_imageno longer matches a product/creative format that originated asdisplay_300x250unless every implementation reimplements canonical matching correctly
Proposed SDK work
Expose documented helpers for common format compatibility checks, for example:
upgrade_legacy_format_id(value) -> FormatId(already effectively present in some surfaces)canonical_format_matches(a, b) -> boolfor equivalence after legacy upgradecanonical_format_satisfies(requested, supported) -> boolfor product/capability gating
The important distinction is that product gating is stricter than equivalence: if the supported/product format declares width, height, or duration_ms, the requested creative format should also declare and match that value. A broad supported format can accept a more specific request, but an under-specified request should not silently match a fixed-size/fixed-duration product.
Acceptance criteria
- SDK exposes a helper or documented pattern for legacy-to-canonical format comparison.
- Tests cover at least
display_300x250vs structureddisplay_imagewidth=300 height=250. - Tests cover the stricter product-gating case: requested
display_imagewith no dimensions does not satisfy supporteddisplay_imagewidth=300 height=250. - Docs/comments make clear which helper is for equivalence and which is for capability satisfaction.
Activity
bokelley commentedon May 27, 2026
Triage
Classification: Feature request
Bucket(s): client (label absent from repo — noted in run summary)
Status: ready-to-implement
What the experts said:
upgrade_legacy_format_idis under-specified — bare strings carry noagent_url;canonical_format_satisfiesneeds a fresh{width,height,duration_ms}exact-match,check_narrows()has inverted semantics and gives wrong answers;(requested, supported)arg order reads backwards.matches/satisfiesnaming is a correctness hazard — direction not encoded; rename toformats_are_equivalent/format_is_supported;find_declaration_by_v1_format_id'sNonepath needs a pointer or adopters won't find these helpers.My take: The failure mode is real and the helpers belong in
adcp.canonical_formats. Resolve two questions first: (1) doesupgrade_legacy_format_idaccept bare strings orFormatId | dictonly (bare strings lackagent_url)?; (2) apply the renames above before coding.Implementation scope:
src/adcp/canonical_formats/compat_helpers.py; re-export from__init__.py+__all__; updatetests/test_canonical_formats_public_api.pyformats_are_equivalent(a, b): delegate to_canonicalize_agent_url()fromformat_options.py— no independent URL normalizationformat_is_supported(requested, supported): fresh exact-match over{width,height,duration_ms}insupported.params—check_narrows()is semantically inverted for this checkfind_declaration_by_v1_format_iddocstring for unexpectedNonereturns (may indicate a legacy id was upgraded)display_300x250↔display_image(300,250)equivalence;display_image()does NOT satisfydisplay_image(300,250)(product gating)Triaged by Claude Code. Session: https://claude.ai/code/cse_01GZYo5dzVRR3PmNR1Jhy7AW
Generated by Claude Code