Repository navigation
Description
This is a suggestion and a question rather than a bug report. The second half asks a specification-design question that an SDK cannot answer alone.
Suggested typing for the consumer side
core/canonical-format-kind.json makes the enum asymmetric on purpose:
Open-enum semantics (normative). … Consumer SDKs MUST treat this enum as open at parse time: an unknown
format_kindvalue MUST be retained as-is on the in-memory object (not silently dropped or rewritten to"custom") and MUST NOT cause the surrounding payload to fail validation. … The producer-side enum stays closed …
The generated field is the bare enum, so a canonical promoted in a later minor release fails validation of the whole payload. Reproduced against adcp==6.6.0:
CreativeAsset2.model_validate({"creative_id": "c", "name": "n", "assets": {},
"format_kind": "a_future_canonical_from_3_2"})
# ValidationError: [{'type': 'enum', ...}]CanonicalFormatKind already subclasses StrEnum, so a union costs little and round-trips correctly:
TypeAdapter(CanonicalFormatKind | str).validate_python("image") # -> CanonicalFormatKind.image ('image')
TypeAdapter(CanonicalFormatKind | str).validate_python("future_x") # -> 'future_x'A known value keeps its enum member, and because the member subclasses str, comparison and serialization behave as before. An unknown value survives as a str, which is what the MUST requires. The change applies wherever the generator emits format_kind: creative-asset, product-format-declaration, creative-manifest, and package-request.
This typing change is not validation. It makes the SDK forward-compatible, and it constrains no producer. That distinction leads to the question.
Open question: where the producer-side constraint belongs
The producer rule in the specification is strict. Sellers "MUST NOT mint ad-hoc format_kind values — use format_kind: "custom" with format_shape + format_schema", and both format_shape and format_schema are "REQUIRED when format_kind: "custom"; otherwise MUST be absent."
Nothing enforces either rule. Measured against ProductFormatDeclaration:
ProductFormatDeclaration.model_validate({"format_kind": "custom", "params": {}})
# ACCEPTED - carries neither format_shape nor format_schema
ProductFormatDeclaration.model_validate({"format_kind": "image", "params": {}, "format_shape": "roadblock"})
# ACCEPTED - carries format_shape on a non-custom kindSo the SDK is strict in the one place the specification mandates openness, and permissive in the place the specification constrains producers. Fixing the typing leaves the second half open.
Here is why I am asking rather than filing a bug. A closed enum that ships a custom escape, whose own requirements go unvalidated, combines the costs of both models: consumers cannot treat the enum as exhaustive, and producers get no enforcement that custom carries the schema that makes it interpretable. If custom is a first-class extension point, then the conditional that makes it usable — format_shape plus format_schema — is the part that most needs validating. If custom is not an extension point, then the twelve canonicals plus the promotion queue in #3666 make a simpler contract.
Do you intend the seller's own boundary to validate this conditional rather than an SDK? If so, please state that normatively: no tool in the chain grades the conditional, so each seller lands somewhere different. I am happy to move this half to adcontextprotocol/adcp if that repository suits it better. The typing suggestion stands on its own either way.
Activity
[-]format_kind typing: suggest CanonicalFormatKind | str, and a question about where the producer-side constraint should be enforced[/-][+]format_kind typing: suggest CanonicalFormatKind | str, and a question about where the producer-side constraint belongs[/+]bokelley commentedon Sep 10, 2026
Triage
Classification: Bug
Bucket(s): validation (label absent from repo — gap noted in run summary)
Status: ready-to-implement
What the experts said:
CanonicalFormatKind | strunion order is correct for Pydantic v2; the fix must targetcanonical_creative.pyoverrides, not just wire-model patches —_canonical_clonere-pinsformat_kindvia explicit override dicts that silently discard any upstream patch;PackageRequest.format_kindis producer-side and out of scope; Part 2 is spec-level and belongs atadcontextprotocol/adcp.CreativeAsset,Creative(overrides ~lines 556/562), andDeliveryCreative(~line 607); regression tests required, analogous totests/test_forward_compat_assets.py;_forward_compat.pywire patches still useful for direct wire-model users but insufficient alone.My take: Part 1 is a normative MUST violation — the SDK rejects exactly the values the spec says MUST be retained. The implementation is wider than it first appears:
canonical_creative.pyre-applies bare-enum overrides at the canonical boundary that silently discard any wire-level-only patch, so the fix belongs in both layers.Implementation scope (Part 1):
src/adcp/types/canonical_creative.py: updateoverrides={"format_kind": ...}—CreativeAssetandCreative(~lines 556/562) →(CanonicalFormatKind | str, Field());DeliveryCreative(~line 607) →(CanonicalFormatKind | str | None, Field(default=None)).src/adcp/types/_forward_compat.py: add module-level imports +_patch_model_field+model_rebuild(force=True)forCreativeManifest.format_kind→CanonicalFormatKind | str | None.tests/test_forward_compat_format_kind.py: assertCreativeAsset,Creative,DeliveryCreative, andCreativeManifesteach accept an unknownformat_kindstring withoutValidationError; assert known values coerce toCanonicalFormatKindmembers.ProductFormatDeclarationdiscriminated union — widening itsLiteraldiscriminators breaks arm selection; a separate catch-all arm design is needed and should be a follow-on issue.pytest tests/test_forward_compat_format_kind.py,mypy src/adcp/types/canonical_creative.py src/adcp/types/_forward_compat.py,ruff check .Part 2: The
format_shape/format_schemarequired-when-custom constraint is a spec design question — whether it should be anif/then/requiredclause in the JSON Schema and whetherformat_schemais truly required or strongly recommended. Please file this half atadcontextprotocol/adcp; SDK enforcement should follow a spec PR rather than precede it.Triaged by Claude Code. Session: https://claude.ai/code/session_01KqbrMMbvw9VVsFS16N32QV
Generated by Claude Code
bokelley commentedon Sep 11, 2026
One correction to the triage note after checking the published artifacts: Part 2 is not an unanswered specification-design question.
The
product-format-declaration.jsonvendored in theadcp==6.6.0wheel already contains anallOfconditional that:format_shapeandformat_schemawhenformat_kind == "custom"; andcustomkinds.The same machine-enforced condition is present in AdCP 3.1.21 and 3.2.0-rc.1. The 6.6.0 generated Pydantic model loses that JSON Schema condition, which is why the two examples in the issue are accepted.
This exact producer-side gap is fixed on the supported stable line: with
adcp==7.0.2, the canonicalFormat/ProductFormatDeclarationboundary rejects both examples (custom formats require format_shapeandformat_shape and format_schema are only valid for custom formats). So there is no protocol issue to split out here. If a 6.x patch is planned, the missing conditional is an SDK code-generation/legacy-model defect.The consumer-side open-enum defect in Part 1 remains valid and independently actionable as triaged.
bokelley commentedon Sep 11, 2026
Triage update — Part 2 correction
Correction acknowledged and verified. @bokelley is right:
product-format-declaration.jsonvendored in 6.6.0 does contain theallOfconditional (both the "custom requiresformat_shape+format_schema" arm and the "non-custom forbids both" arm); the constraint was never missing from the spec. The prior triage incorrectly routed Part 2 toadcontextprotocol/adcp— sorry for the misdirection, @KonstantinMirin.Part 2 — revised:
main(7.x): already fixed —canonical_creative.py:Format._validate_custom_shape(lines 516–523) enforces both conditions and raises the error strings quoted in @bokelley's note.canonical_decl.py:ProductFormatDeclarationhas_check_mutual_exclusionbut no_validate_custom_shape. If a 6.x patch release is planned, the fix is an additive model validator ported fromcanonical_creative.py:Format— no code-gen re-run needed (canonical_decl.pyis the hand-rolled override layer). Non-breaking: only spec-invalid payloads that currently slip through start failing.Part 1 — unchanged: the open-enum implementation brief from the prior triage stands.
Triaged by Claude Code. Session: https://claude.ai/code/session_01UqAGHpwxigFwEjDbKLjfuq
Generated by Claude Code