Skip to content

Format.canonical_parameters drops format_kind and params on the 3.1 line (generated ProductFormatDeclaration ignores the oneOf branches) #1275

Closed

Description

@KonstantinMirin

Summary

On the 3.1 line (6.6.0 and 7.0.3), parsing a Format silently drops canonical_parameters.format_kind and canonical_parameters.params. Re-serializing the parsed object then emits a declaration that the SDK's own bundled 3.1/core/product-format-declaration.json rejects.

Cause

core/product-format-declaration.json (3.1) is a discriminated oneOf with 13 branches, and every branch requires format_kind and params. The generated class adcp.types.generated_poc.core.product_format_declaration.ProductFormatDeclaration keeps only the shared base properties (format_option_id, publisher_domain, display_name, canonical_formats_only, experimental, ...) and has extra="ignore". As a result, both discriminated fields are discarded on parse.

Format.canonical_parameters is typed with that generated class. The hand-written adcp.types.canonical_decl.ProductFormatDeclaration, exported as adcp.types.ProductFormatDeclaration, does have format_kind/params, but Format doesn't use it, and it isn't a subclass of the generated class.

Reproduction

import importlib.metadata as m
from adcp.types.generated_poc.core.format import Format

f = Format.model_validate({
    "format_id": {"agent_url": "https://creative.example.com", "id": "display_300x250_image_2x"},
    "name": "Medium Rectangle - Image (2x)",
    "canonical_parameters": {"format_kind": "image", "params": {"width": 300, "height": 250, "pixel_ratios": [2]}},
})
print(m.version("adcp"), f.model_dump(mode="json", exclude_none=True)["canonical_parameters"])

Run with uv run --no-project --with "adcp==<v>" python probe.py:

SDK Bundled spec Output
6.6.0 3.1.1 {'canonical_formats_only': False, 'experimental': False}
7.0.3 3.1.15 {'canonical_formats_only': False, 'experimental': False} (the generated module is byte-identical to 6.6.0's)
8.0.0rc3 3.2.0-rc.7 format_kind and params kept: the class is now a RootModel union with one typed branch per kind

Impact

A seller that relays a creative agent's list_creative_formats catalog through these types serves canonical_parameters without format_kind/params. Buyers validating against the 3.1 response schema reject it. We found this when a creative agent at v3.1.24 started emitting the retina image formats (display_*_image_2x).

Request

Could the 3.1 line (7.x) get the same codegen fix 8.0 has? The fix is to generate the oneOf branches so format_kind and params survive parsing. Until then, our workaround is a local subclass of the generated class that adds format_kind: CanonicalFormatKind and params: dict[str, Any], with Format.canonical_parameters narrowed to it.

A side note on 8.0.0rc3

The output there isn't the input that was sent: params comes back with schema defaults filled in that the agent never sent, such as slots, v1_translatable, asset_source and buyer_asset_acceptance. That may be intended, but it means a seller relaying a catalog re-emits fields the creative agent did not author.

Activity

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

    @bokelley
    Contributor

    Triage

    Classification: Bug
    Bucket(s): validation, client
    Status: ready-for-human
    Milestone: (omitted — backport policy decision needed)

    What the experts said:

    • ad-tech-protocol-expert: Blocker on the 3.1 line — format_kind and params are required in the 3.1 spec's discriminated oneOf; extra="ignore" discards them silently, making format routing and closed-set enforcement dead code on 6.6.0 and 7.0.3. The fix scope is well-defined (touches only the alias/public-surface layer, no generated-poc changes), but a backport also requires a 7.x maintenance branch to be created. The round-trip inflation in 8.0.0rc3 (defaults filling in absent params fields) is a distinct, separate bug.
    • code-reviewer: No 7.x branch exists in this repo. Creating one requires a maintainer to set maintenance policy, a release workflow, and decide between re-running codegen (600+ file numbering churn risk per CLAUDE.md) or cherry-picking the hand-written canonical_decl.py approach. Out of scope for triage. 8.0.0 has zero residual risk — both canonical_parameters and the public adcp.types.ProductFormatDeclaration are correctly fixed.

    My take: The bug is confirmed and serious: the 3.1 SDK silently drops two required spec fields, breaking any seller that relays a list_creative_formats catalog from a 3.1.24+ creative agent. 8.0.0 already has the full fix. The open question is whether to open a 7.x maintenance branch — that's a policy call, not a code decision.

    Flagging for @bokelley:

    • Does the project intend to maintain a 7.x patch line? If yes, the backport is technically a cherry-pick of canonical_decl.py, aliases.py:405, and the _eager.py binding (no generated-poc changes needed).
    • The secondary note about 8.0.0rc3 inflating params with schema defaults is a real, separate bug. Worth a new issue with a failing round-trip test before the 8.0.0 GA.

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


    Generated by Claude Code

  3. added
    bugSomething isn't working
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 1, 2026
  4. KonstantinMirin commented on Oct 1, 2026

    @KonstantinMirin
    CollaboratorAuthor

    This might be a good point to voice my concern about "Does the project intend to maintain a 7.x patch line?"
    As an implementer, I find it very frustrating that the patch-type fixes rarely find their way to the previous versions. And newer versions break too much of the internal structure. E.g., 6.6 and 7.2 treat Creatives very differently, with no way to upgrade in stages.

    So I would very much like to see the world where fixes are backported to all the SDK versions. Happy to contribute there as needed.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions