Filed off second SDK-implementor review on #3307.
Problem
A v2-native seller's flatten wrapper (v2 → v1 demotion path) emits a format_id like acme/canonical_image_300x250 that no buyer's catalog allowlist knows. v1 buyers reading the product will get a format identifier they can't match to anything in their catalog DB, and downstream allowlist/blocklist logic fails or skips the inventory.
What this issue tracks
A docs/SHOULD note (not a normative spec change) on canonical-formats-migration.mdx covering the v2-native → v1-wrapper path:
- Sellers emitting v1
format_ids synthesized from v2 declarations SHOULD declare the synthetic IDs in their published format catalog (the seller's static format file referenced by their adcp-resource manifest), so v1 buyers reading list_creative_formats see the same identifiers as appear on Product.format_ids.
- Synthetic IDs SHOULD use the
<seller_domain>/canonical_<format_kind>_<param_summary> pattern when no preexisting v1 name exists (e.g., acme.adcp/canonical_image_300x250) so buyers can pattern-match the convention.
- Sellers SHOULD avoid the AAO-mirror-style
aao-synth/* namespace (explicitly rejected on this PR's design); synthetic IDs are seller-scoped.
- Adopter expectation: v1-only buyers reading a v2-native product see fewer format_id entries than v2-aware buyers see on format_options, because the seller chose not to synthesize. This is expected and the
canonical_formats_only: true marker on the v2 declaration is the wire signal.
Why this is small
Mostly docs. No schema change. Tracking separately because the inline normative section on #3307 covers the v2_only marker but not the synthetic-ID emission pattern for flatten wrappers.
Tracking: GA-blocking only if flatten-wrapper adopters report confusion in beta; otherwise post-GA docs polish.
Filed off second SDK-implementor review on #3307.
Problem
A v2-native seller's flatten wrapper (v2 → v1 demotion path) emits a
format_idlikeacme/canonical_image_300x250that no buyer's catalog allowlist knows. v1 buyers reading the product will get a format identifier they can't match to anything in their catalog DB, and downstream allowlist/blocklist logic fails or skips the inventory.What this issue tracks
A docs/SHOULD note (not a normative spec change) on canonical-formats-migration.mdx covering the v2-native → v1-wrapper path:
format_idssynthesized from v2 declarations SHOULD declare the synthetic IDs in their published format catalog (the seller's static format file referenced by their adcp-resource manifest), so v1 buyers readinglist_creative_formatssee the same identifiers as appear onProduct.format_ids.<seller_domain>/canonical_<format_kind>_<param_summary>pattern when no preexisting v1 name exists (e.g.,acme.adcp/canonical_image_300x250) so buyers can pattern-match the convention.aao-synth/*namespace (explicitly rejected on this PR's design); synthetic IDs are seller-scoped.canonical_formats_only: truemarker on the v2 declaration is the wire signal.Why this is small
Mostly docs. No schema change. Tracking separately because the inline normative section on #3307 covers the v2_only marker but not the synthetic-ID emission pattern for flatten wrappers.
Tracking: GA-blocking only if flatten-wrapper adopters report confusion in beta; otherwise post-GA docs polish.