SyncCreativesResponse `Creative` item missing 9 of 12 spec-defined fields

[KonstantinMirin]

Hi — flagging a contract gap between the Python SDK and the AdCP spec it targets.

Spec

In static/schemas/source/creative/sync-creatives-response.json, the per-creative result item (oneOf[0].properties.creatives.items) defines 12 properties:

field	required
creative_id	yes
action	yes
account	no
assigned_to	no
assignment_errors	no
changes	no
errors	no
expires_at	no
platform_id	no
preview_url	no
status	no
warnings	no

This schema shape is stable across the spec range relevant to this SDK — verified identical at:

• tag v3.1.0-beta.3 (commit 727085264) — the spec target stamped in the 5.7.0 package description ("5.7.0 targets AdCP spec 3.1.0-beta.3")
• a downstream pin at adcp commit 04f59d2d5 (2026-05-13)
• origin/main today

SDK 5.7.0

adcp/types/generated_poc/creative/sync_creatives_response.py emits a Creative(AdcpVersionEnvelope) Pydantic class with only 3 declared fields plus 2 inherited from the envelope:

```python
class Creative(AdcpVersionEnvelope):
creative_id: str
action: CreativeAction
errors: Optional[list[Error]] = None
```

Pydantic introspection:

```

from adcp.types.generated_poc.creative.sync_creatives_response import Creative
list(Creative.model_fields)
['adcp_version', 'adcp_major_version', 'creative_id', 'action', 'errors']
```

Gap

The SDK is missing 9 of 12 spec-defined fields: account, assigned_to, assignment_errors, changes, expires_at, platform_id, preview_url, status, warnings.

All 9 are optional in the spec, which suggests the codegen path is filtering on required[] and dropping the rest. By the AdCP contract these are buyer-observable fields (e.g. status carries the review-lifecycle signal, assigned_to reports successful assignments, errors is only meaningful when read alongside action). Without typed access, callers either drop to raw dict parsing or miss the data entirely.

For comparison, the TypeScript SDK at adcontextprotocol/adcp-client (src/lib/types/core.generated.ts, SyncCreativesSuccess.creatives[]) emits the full 12-field shape.

Suggested fix

Whatever generator step writes generated_poc/creative/sync_creatives_response.py should walk the full properties map of oneOf[0].properties.creatives.items, not just required[]. The Optional[...] typing for the new fields is straightforward once they're enumerated.

Happy to provide a reduction case or help test a fix.

[bokelley]

Triage

Classification: Bug
Bucket(s): validation (codegen fidelity against spec) — no matching repo labels found for validation or client
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: status is a spend-gating signal (buyer polling loop branches on processing/pending_review/approved); losing typed access there is especially harmful. _forward_compat.py injection is the right pattern; non-breaking.
• code-reviewer: inadvertently reviewed the v2.5 schema (SDK targets 3.1.0-rc.9 — account and status are present in the current spec, confirmed). Valid implementation note: _patch_model_field currently assumes the field exists; injecting new fields needs explicit default=None in the FieldInfo kwargs.

My take: Gap confirmed against 3.1.0-rc.9 — schemas/cache/3.1.0-rc.9/creative/sync-creatives-response.json lists all 12 fields. Adding 9 optional fields to Creative (which already has extra='allow') is non-breaking; callers reading via .model_extra["status"] today will get a typed attribute instead with zero API breakage.

Implementation scope:

• src/adcp/types/_forward_compat.py: add _patch_creative_item_fields(). Extend _patch_model_field or use a local helper that passes default=None when injecting absent fields. Inject these 9 onto Creative (from generated_poc.creative.sync_creatives_response): account: Account | None, status: CreativeStatus | str | None, platform_id: str | None, changes: list[str] | None, warnings: list[str] | None, preview_url: str | None, expires_at: str | None, assigned_to: list[str] | None, assignment_errors: dict[str, str] | None. Call Creative.model_rebuild(force=True). This patch survives make regenerate-schemas (only generated_poc/ is wiped).
• tests/: assert all 12 field names appear in Creative.model_fields; round-trip parse a payload containing all 12 fields cleanly.
• Required checks: pytest on affected tests, mypy src/, ruff check . + black --check ..
• Follow-on issue recommended: fix scripts/generate_types.py to hoist the anonymous creatives.items object into a named $defs entry before passing to datamodel-code-generator, so the next make regenerate-schemas produces the correct class without the shim.

---

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

---

Generated by Claude Code

[KonstantinMirin]

Follow-up after tracing the codegen pipeline a bit further — sharing a finding that sharpens the diagnosis.

How the field set ends up at 3

Looking at the generated file's own header:

# generated by datamodel-codegen:
#   filename:  creative/sync_creatives_response.json
#   timestamp: 2026-05-22T13:15:12+00:00

…and the inline comment a few lines down:

# Backward-compatible SDK response arms. Upstream beta 3 schemas collapse this
# task response to the common protocol envelope, but the Python SDK keeps the
# historical numbered variants as ergonomic construction/parsing aliases.

This pattern appears in 18 task-response files across the SDK (sync_accounts_response.py, log_event_response.py, get_rights_response.py, etc.), and from the issue context in #822 it traces back to scripts/post_generate_fixes.py::_write_if_needed, which removes the datamodel-codegen output for these task responses and appends hand-written "manual response arm" classes in its place.

So the codegen path is:

1. datamodel-codegen produces the spec-faithful types from the schema cache (which would emit all 12 fields on Creative).
2. post_generate_fixes.py then overwrites that file with hand-written manual response arms.
3. The hand-written Creative(AdcpVersionEnvelope) has 3 declared fields (+2 from the envelope).

That much I already understood when I filed this issue. The framing I want to correct is the rationale in step 3.

"Historical numbered variants" — verifying that history

The inline comment implies the 3-field hand-written shape is "historical" — i.e., it was once the actual spec shape and is being preserved for backwards compatibility. I traced this through the adcontextprotocol/adcp repo to check.

sync-creatives-response.json was introduced in adcp commit f460eced1 (2026-03-12, "feat: creative library protocol — list_creatives, sync_creatives, …"). At that first commit, oneOf[0].properties.creatives.items.properties already contained 11 of the current 12 fields:

account, action, assigned_to, assignment_errors, changes, creative_id, errors,
expires_at, platform_id, preview_url, warnings

with required: ["action", "creative_id"].

The 12th field (status) was added later but still well before our reference window. At every tagged release between the schema's introduction and v3.1.0-beta.3 (the SDK 5.7.0 target), the Creative item has carried at least 11 properties.

There is no commit in the schema's history at which Creative had only creative_id, action, and errors. The 3-field hand-written shape isn't preserving a past spec version — it doesn't match any past spec version.

That makes the situation a little different from "the hand-written stub fell out of date as the spec evolved." It's more accurate to say the hand-written stub has never matched the spec it's generated from, on this task. The codegen pipeline has been producing the right type all along; the post-processing step has been silently substituting a non-spec shape since the manual arms were added.

Suggested follow-up

If the manual-response-arms mechanism is intentional for ergonomic reasons (e.g., easier construction in tests), it would be helpful to either:

• regenerate the manual arms from the schema (so they actually carry the 11–12 fields), OR
• remove the manual override for this file and let datamodel-codegen's output stand, OR
• if neither is feasible short-term, document on the Creative class that consumers should reach through model_extra for account, assigned_to, assignment_errors, changes, expires_at, platform_id, preview_url, status, and warnings, since extra='allow' lets those land at parse time even though they're not typed.

Happy to help test a fix or contribute a regression check that diffs codegen output against schema properties for these manual-arm files. Not blocking anything urgently from my side — just thought the schema-history check was worth recording on the issue.

[bokelley]

Triage — Follow-up

Status: ready-to-implement (unchanged)

Thanks for the schema history trace — confirms the stub was never spec-faithful, not simply stale. One concrete correction to the follow-on in the prior brief:

The root-cause script is scripts/post_generate_fixes.py (_write_if_needed), not scripts/generate_types.py as the prior brief stated. Anyone filing the follow-on issue should target the right file.

Revised follow-on scope: post_generate_fixes.py applies this same override pattern across 18 task-response files. A systemic fix there could close the same gap for all 18 simultaneously — worth scoping as a separate issue rather than a one-file patch, since it touches the codegen infrastructure for the entire manual-response-arm layer.

Immediate fix path unchanged: the _forward_compat.py shim described in the prior brief remains the right short-term approach for this issue; it targets Creative in isolation, doesn't touch post_generate_fixes.py, and survives make regenerate-schemas.

---

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

---

Generated by Claude Code

[bokelley]

Fixed by #922 (merged). The hand-authored Creative snippet that shipped only 3 of 12 fields is gone — #922 removed the _write_if_needed layer and schema-derives the arm, so all 12 rc.9 fields (account, status, assigned_to, assignment_errors, changes, expires_at, platform_id, preview_url, warnings + the existing creative_id/action/errors) are now typed directly from the schema.