Reserve `ctx_metadata` as adapter-internal round-trip key on resource objects

[bokelley]

Proposal

Reserve ctx_metadata as a top-level optional key on the following AdCP resource objects, with semantics: publisher-to-SDK round-trip cache for adapter-internal state. MUST be stripped before wire egress. MUST NOT be relied on by buyers.

Resources that get the reserved key:

• Product
• MediaBuy
• Package
• Creative
• AudienceSegment
• Signal
• RightsGrant
• PropertyList
• CollectionList

Why this needs spec coordination

This is a non-binding convention, not a wire-protocol field. AdCP buyers never see ctx_metadata — SDKs strip it from outgoing payloads. But two SDKs converging on the same field name by accident is interop debt: a third SDK (Go, Rust, the next salesagent rewrite) will pick a different name and break the pattern. One paragraph in the spec turns it into a convention that survives ecosystem expansion.

Prior art — Prebid salesagent

The reference prebid/salesagent Python implementation uses an implementation_config JSON column on the Product model for the same purpose (GAM ad_unit_ids per product, key_value_pairs, placement_ids, etc.). Keyword-name implementation_config is salesagent-specific; the convention is the round-trip pattern itself.

Wire-compat check

All 9 resource schemas above already declare additionalProperties: true in AdCP 3.0.0. Adopting ctx_metadata as a recognized top-level key is forward-compatible at the wire level — no schema changes needed, just spec note acknowledging the reserved name.

ctx_metadata does not collide with any existing AdCP 3.0 wire field across core/, signals/, creative/, media-buy/, property/, governance/, brand/ schemas. Distinct from:

• ext — vendor-namespaced, buyer-visible (different semantics)
• context — caller-echoed (different semantics)

Implementation

@adcp/sdk 6.1 ships the TypeScript-side CtxMetadataStore (in-memory + Postgres backends) with the field name ctx_metadata. The Python SDK (adcp-client-python PR #316) is in design phase and will adopt the same name; spec note locks the convention before two SDKs ship with divergent names.

Ask

Add a one-paragraph spec note (probably in core/conventions.md or equivalent) reserving the key and documenting the round-trip semantics. Not changing wire payloads, not changing schemas. Just naming.

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• adtech-product-expert: Blocker — wire-compat claim is false for 2 of 9 named schemas: property/property-list.json and collection/collection-list.json both declare additionalProperties: false. An SDK writing ctx_metadata onto those objects will fail strict validation. Blocker — MUST-strip with no warning mechanism creates silent data loss for any operator already using that key name in a custom adapter; needs at minimum a MUST-log-warning clause. Concern — ctx_metadata reads as "metadata about the context" (a live AdCP concept), and ext._sdk would slot into the existing ext discipline with zero schema gap.
• ad-tech-protocol-expert: running at comment time; findings will surface on re-triage if needed.

My take: The coordination rationale is solid and the timing is right — locking the convention before the Python SDK ships is the correct move. But two specific gaps need owner input before this can execute.

Option A — Narrow scope to 7 resources, keep top-level key, add MUST-warn:

# proposed spec note (docs/spec-guidelines.md or new core/conventions.md)
+ ## Reserved SDK-internal key: `ctx_metadata`
+ `ctx_metadata` is reserved as a top-level adapter-internal round-trip key on
+ Product, MediaBuy, Package, Creative, AudienceSegment, Signal, and RightsGrant.
+ Adapters MUST strip this key before wire egress and MUST emit a warning-level
+ log entry when stripping, so operators can detect accidental key collisions.
+ PropertyList and CollectionList are excluded (additionalProperties: false —
+ follow-up PR required to extend the convention there).

Keeps @adcp/sdk 6.1 field name intact. Requires a follow-up schema PR to flip the two excluded resources.

Option B — Route via ext._sdk namespace, zero schema gap:

- "ctx_metadata": { "gam_unit_ids": [...], "placement_ids": [...] }
+ "ext": { "_sdk": { "gam_unit_ids": [...], "placement_ids": [...] } }

ext is additionalProperties: true everywhere by AdCP convention (spec-guidelines §Platform Agnosticism). No schema gap, fits existing ext discipline, underscore prefix signals internal-use by convention. Requires SDK 6.1 field migration.

@bokelley, your call: A (narrow scope + MUST-warn) or B (ext._sdk)?

---

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

---

Generated by Claude Code