format_kind typing: suggest CanonicalFormatKind | str, and a question about where the producer-side constraint belongs

[KonstantinMirin]

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_kind value 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 kind

So 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.

[bokelley]

Triage

Classification: Bug
Bucket(s): validation (label absent from repo — gap noted in run summary)
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: CanonicalFormatKind | str union order is correct for Pydantic v2; the fix must target canonical_creative.py overrides, not just wire-model patches — _canonical_clone re-pins format_kind via explicit override dicts that silently discard any upstream patch; PackageRequest.format_kind is producer-side and out of scope; Part 2 is spec-level and belongs at adcontextprotocol/adcp.
• code-reviewer: Three public models need updating — CreativeAsset, Creative (overrides ~lines 556/562), and DeliveryCreative (~line 607); regression tests required, analogous to tests/test_forward_compat_assets.py; _forward_compat.py wire 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.py re-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: update overrides={"format_kind": ...} — CreativeAsset and Creative (~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) for CreativeManifest.format_kind → CanonicalFormatKind | str | None.
• tests/test_forward_compat_format_kind.py: assert CreativeAsset, Creative, DeliveryCreative, and CreativeManifest each accept an unknown format_kind string without ValidationError; assert known values coerce to CanonicalFormatKind members.
• Skip ProductFormatDeclaration discriminated union — widening its Literal discriminators breaks arm selection; a separate catch-all arm design is needed and should be a follow-on issue.
• Checks: pytest tests/test_forward_compat_format_kind.py, mypy src/adcp/types/canonical_creative.py src/adcp/types/_forward_compat.py, ruff check .
• Non-breaking: strictly more permissive on the consumer side; producer paths and existing enum member behavior unchanged.

Part 2: The format_shape/format_schema required-when-custom constraint is a spec design question — whether it should be an if/then/required clause in the JSON Schema and whether format_schema is truly required or strongly recommended. Please file this half at adcontextprotocol/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]

One correction to the triage note after checking the published artifacts: Part 2 is not an unanswered specification-design question.

The product-format-declaration.json vendored in the adcp==6.6.0 wheel already contains an allOf conditional that:

• requires format_shape and format_schema when format_kind == "custom"; and
• forbids both fields for non-custom kinds.

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 canonical Format/ProductFormatDeclaration boundary rejects both examples (custom formats require format_shape and format_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]

Triage update — Part 2 correction

Correction acknowledged and verified. @bokelley is right: product-format-declaration.json vendored in 6.6.0 does contain the allOf conditional (both the "custom requires format_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 to adcontextprotocol/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.
• 6.x: SDK code-generation defect confirmed. canonical_decl.py:ProductFormatDeclaration has _check_mutual_exclusion but no _validate_custom_shape. If a 6.x patch release is planned, the fix is an additive model validator ported from canonical_creative.py:Format — no code-gen re-run needed (canonical_decl.py is 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