create-media-buy submitted-branch schema underspecified — missing required status + task_id

[bokelley]

What

schemas/cache/media-buy/create-media-buy-async-response-submitted.json (the submitted-branch schema referenced by create-media-buy-response.json's 3-branch anyOf) currently only lists context and ext in properties and describes itself as "usually empty or just context."

The main create-media-buy-response.json Branch 3 requires status: const "submitted" + task_id (string) — that's the AdCP async-task contract: a buyer needs a polling handle.

Impact

When a platform implementation forgets task_id in the submitted envelope, the SDK's per-tool output validator (FastMCP / jsonschema) surfaces a misleading error. jsonschema's deepest-schema-path heuristic picks the enum violation on status inside the success branch (depth 7) over the required: task_id violation in the submitted branch (depth 3). The reported error reads:

Output validation error: 'submitted' is not one of ['pending_creatives', 'pending_start', 'active', 'paused', 'completed', 'rejected', 'canceled']

…which sends implementors hunting in the wrong direction. Verified empirically with jsonschema on the union schema: adding task_id to the same payload validates cleanly.

If the submitted-branch schema itself enumerated status (const) and required task_id, the SDK's opt-in validate_response() (which routes on status="submitted" and validates against this file) would catch the missing task_id with a clear, branch-local message instead of letting it propagate to the union validator's misleading deepest-error pick.

Proposed change

In static/schemas/v1/media-buy/create-media-buy-async-response-submitted.json:

{
  "properties": {
    "status": { "const": "submitted" },
    "task_id": { "type": "string", "description": "Polling handle for the async task" },
    "context": { ... existing ... },
    "ext": { ... existing ... }
  },
  "required": ["status", "task_id"]
}

(Adjust to match the spec repo's actual file location and existing structure.)

Surfaced by

adcp-client-python issue #570 — salesagent live GAM CRUD probe. The SDK side has been addressed in adcp-client-python#575 (return-type + alias) but the underlying schema gap is upstream.

[bokelley]

Triage

Classification: Bug (schema defect — sub-schemas inconsistent with parent contract)
Bucket(s): spec/protocol, schema, media-buy
Status: drafting-pr

What the experts said:

• ad-tech-protocol-expert: Non-breaking patch-eligible clarification; the IETF errata test is satisfied — any conformant 3.0.0 implementation already emits both fields (the parent oneOf already mandates them). Same defect exists in all six async submitted sub-schemas; fix must cover all six.
• adtech-product-expert: Blocker in practice — DSP/platform engineers integrating async flows hit a misleading status enum error instead of the actionable required: task_id message; adoption friction is real and the fix has zero migration cost for conformant implementations.
• code-reviewer (pre-PR): Approved; noted estimated_completion description stub in get-products as a nit (pre-existing).
• ad-tech-protocol-expert (pre-PR): Approved; field set matches AdCP async-task polling contract verbatim from parent schemas.

My take: All six *-async-response-submitted.json sub-schemas were systematically underspecified — "usually empty or just context" descriptions directly contradicting the parent oneOf branches that already require status and task_id. PR #4079 fixes all six with the fields copied verbatim from their respective parent submitted branches. Changeset is patch; targets main per the cherry-pick convention, with a note to cherry-pick to 3.0.x after merge.

Drafting PR #4079: add status: const "submitted", task_id, message, errors + required: ["status", "task_id"] to all six async submitted sub-schemas.

---

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

---

Generated by Claude Code