Skip to content

feat(canonical-formats): Pythonic v1↔v2 projection layer — parallel to adcp-client #1815 #741

Closed

Description

@bokelley

3.1 GA gating — port the v1↔v2 projection layer from the TypeScript reference (adcp-client #1815) into the Python SDK.

Why

Schemas landed in AdCP #3307 / #4770: 12 canonical formats, ProductFormatDeclaration discriminator, 14 reference fixtures, pixel_tracker asset with bidirectional v1↔v2 contract, canonical-projection-ref.json (object-form canonical: on v1 catalog entries), v1-canonical-mapping.json registry.

Without Python SDK support, Python adopters can't consume canonical-formats cleanly — they'd hand-roll v1↔v2 translation per integration. The TS prototype (adcontextprotocol/adcp-client#1815) is the reference; the Python work mirrors it.

What's needed

  1. Type generation — generate Pydantic models from canonical-formats schemas. 13 format_kind values as a tagged union; params typed per canonical; slots[] typed against asset-group vocabulary; pixel_tracker discriminated by event × method.

  2. v2 → v1 projection — mirror the resolution order in v1-canonical-mapping.json:

    • format_kind: \"custom\" + canonical_formats_only: true → no v1 emit
    • v1_format_ref[] set → use directly (multi-size fan-out per ref)
    • Else: registry lookup → structural match → FORMAT_PROJECTION_FAILED advisory
  3. v1 → v2 projection — invert via the v1 catalog's canonical: object-form annotation ({ kind, asset_source?, slots_override? }). Family-level structural match emits FORMAT_DECLARATION_V1_AMBIGUOUS advisory.

  4. Bidirectional pixel_tracker contract — implement the cross-version downgrade/upgrade table in pixel-tracker-asset.json description. Emit PIXEL_TRACKER_LOSSY_DOWNGRADE / PIXEL_TRACKER_UPGRADE_INFERRED advisories on errors[].

  5. Multi-size fan-out — params.sizes[] count > v1_format_ref[] count emits FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE.

  6. Closed-set semantics on format_options[] — sellers MUST reject create_media_buy targeting any format_kind outside the list. SDK helper to validate manifests against the closed set before the seller call.

  7. Test against the 14 reference fixtures at static/examples/products/canonical/ in the main repo. Each fixture should round-trip cleanly: v1 read → v2 projection → v1 reprojection should produce the same format_ids[].

References

  • adcp-client chore(main): release 9.5.0 #1815 — TypeScript reference (draft)
  • AdCP #3307 — canonical-formats GA work (merged)
  • AdCP #4770 — round-2 follow-ups including native_in_feed + Taboola fixture
  • docs/creative/canonical-formats.mdx — full reference
  • docs/creative/canonical-formats-migration.mdx — per-adopter migration paths
  • pixel-tracker-asset.json description — bidirectional contract tables

Out of scope

  • Server-side flatten wrapper (separate work)
  • Conformance storyboard (separate AdCP work)

🤖 Generated with Claude Code

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 19, 2026
  2. bokelley commented on May 19, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): client, validation, cross-repo (no matching labels exist in this repo — flagged in run summary)
    Status: deferred

    What the experts said:

    • ad-tech-protocol-expert: Blocked on three hard prerequisites — canonical-formats schemas absent from local cache (v3.0.7 has no canonical/ tree), v1-canonical-mapping.json and the four new error codes don't exist locally, and implementing against the draft TS reference risks silent projection-logic drift if the resolution order changes before chore(main): release 9.5.0 #1815 merges.
    • code-reviewer: Not ready to execute; same three blockers — missing schema bundle, draft TS reference, and 14 round-trip fixtures that live in adcontextprotocol/adcp and must be vendored into tests/fixtures/canonical/ before item 7 is testable in CI.

    My take: All three prerequisites must land in sequence before Python implementation begins: (1) a 3.1+ bundle must be published at adcontextprotocol.org and pulled via scripts/sync_schemas.py, (2) adcp-client #1815 must exit draft so the projection resolution order and advisory contract are stable, and (3) the 14 canonical-format fixtures must be vendored locally. Once those are in place, items 1–5+7 are a cohesive single PR; item 6 (closed-set format_options[] validator) can follow.

    Blocked-on: adcontextprotocol/adcp-client#1815 — resurfaces on merge


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


    Generated by Claude Code

  3. added
    enhancementNew feature or request
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 19, 2026
  4. bokelley commented on May 23, 2026

    @bokelley
    ContributorAuthor

    Status refresh: the original blocker adcontextprotocol/adcp-client#1815 was closed as superseded, and the TypeScript reference work landed through adcontextprotocol/adcp-client#1882 and #1890. This is no longer blocked on a draft TS prototype. Remaining blocker is local Python 3.1/canonical-format schema/codegen availability plus vendoring the reference fixtures; keep open, but classify as deferred to the 3.1/8.0 enablement batch rather than blocked on #1815.

  5. bokelley commented on May 23, 2026

    @bokelley
    ContributorAuthor

    Triage (status update — 2026-05-23)

    Classification: Feature request
    Bucket(s): client, validation, cross-repo
    Status: deferred

    What changed: adcontextprotocol/adcp-client#1815 was closed as superseded; the TypeScript reference implementation landed through adcp-client#1882 and #1890. The prior "Blocked-on: #1815 — resurfaces on merge" trigger is now void.

    Remaining blockers (unchanged from original expert assessment):

    1. Python 3.1 canonical-format schema bundle not yet published/available for scripts/sync_schemas.py — the generated Pydantic models (item 1) can't be produced without it.
    2. 14 reference fixtures not yet vendored into tests/fixtures/canonical/ — item 7 (round-trip test) requires them.

    My take: Disposition is still deferred, but the linkage shifts from "blocked on draft TS ref" to "blocked on 3.1/8.0 schema-enablement batch." Once the 3.1 schema bundle is published and fixtures are vendored, items 1–5+7 form a cohesive single PR.

    Resurfaces when: the 3.1 canonical-format schema bundle is available via scripts/sync_schemas.py.


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


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions