Codegen: Zod schemas for FormatAssetSlot, and tighten Format.assets typing

[bokelley]

Summary

Two related codegen gaps around format asset slots, both surfacing as friction for SDK consumers that want to validate or type-narrow Format.assets from creative agents:

1. Zod schemas for slot shapes are missing. The codegen produces *AssetRequirementsSchema (image, video, text, …) at dist/lib/types/schemas.generated.d.ts, and TS types for the wrapping slot shapes (IndividualAssetSlot, RepeatableGroupSlot, FormatAssetSlot) at dist/lib/types/format-asset-slots.d.ts. But it doesn't generate Zod for the slot shapes — there's no IndividualAssetSlotSchema, RepeatableGroupSlotSchema, or FormatAssetSlotSchema.

2. Format.assets is typed loosely. Per dist/lib/types/format-asset-slots.d.ts:

   export interface BaseIndividualAssetSlot {
     item_type: 'individual';
     asset_id: string;
     asset_role?: string;
     required: boolean;
     overlays?: Overlay[];
   }

   Whereas the wire format (and the proper IndividualAssetSlot discriminated union in the same file, line 77) carries asset_type plus a discriminated requirements. If Format.assets were typed as FormatAssetSlot[], consumers would get proper narrowing.

Why this matters

Today, consumers reading agent.listCreativeFormats() get back Format objects whose assets[] are typed as the narrow base. The fields are present in JSON but not in TS types. We work around this with casts:

// from a downstream consumer, paraphrased
const assetList = f.assets ?? (rawFormat.assets_required as typeof f.assets)
return assetList.map((a) => {
  const raw = a as unknown as Record<string, unknown>
  return {
    asset_type: String(raw.asset_type ?? raw.type ?? ''),
    description: String(raw.description ?? ''),
    requirements: raw.requirements as Record<string, unknown>,
    // ...
  }
})

Two costs:

1. No runtime validation of slot shape. Without a slot-level Zod schema, consumers either build their own (forking the type definitions) or trust the wire format. We'd build our own; we'd rather not.
2. Lost type narrowing. A consumer that reads slot.asset_type === "text" should get slot.requirements: TextAssetRequirements | undefined for free. Today they have to cast.

Proposed fix

(A) Generate Zod for slot shapes

Extend the JSON-Schema → Zod codegen (or whatever step produces schemas.generated.ts) to cover:

• BaseIndividualAssetSlotSchema, BaseGroupAssetSlotSchema
• IndividualImageAssetSlotSchema, IndividualVideoAssetSlotSchema, … (all 14 individual variants)
• IndividualAssetSlotSchema — the discriminated union over asset_type
• GroupAssetSlotSchema, RepeatableGroupSlotSchema
• FormatAssetSlotSchema = IndividualAssetSlotSchema | RepeatableGroupSlotSchema

These shapes are already declared as TS interfaces in format-asset-slots.d.ts; the Zod codegen just needs to follow.

(B) Tighten Format.assets typing

Change Format.assets (in tools.generated) from the narrow base shape to FormatAssetSlot[]. Same wire format, more honest type. Eliminates the cast pattern shown above.

Workarounds in the meantime

We'll likely hand-roll a Zod discriminated union locally that satisfies IndividualAssetSlot from the SDK types (using satisfies z.ZodType<IndividualAssetSlot> to anchor compile-time alignment). When (A) lands, we delete ours and import yours.

Cross-links

• AdCP RFC tracking input vocabulary: adcontextprotocol/adcp#3305
• Related downstream issue (proposing input-slot vocabulary additions): adcontextprotocol/adcp#4331
• Downstream consumer that already adopted AssetRequirementsSchema from this SDK: scope3data/agentic-api#2366

Versions

@adcp/sdk@6.5.0. Reproducible by inspecting dist/lib/types/format-asset-slots.d.ts (TS-only types) vs dist/lib/types/schemas.generated.d.ts (no slot Zod schemas).

[bokelley]

---

Generated by Claude Code

[bokelley]

Triage

Classification: Bug (Part A: missing feature) + Bug (Part B: incorrect type)
Bucket(s): schema-sync, library (label names unverified — applying in comment)
Status: drafting-pr (Part A shipped); ready-for-human (Part B)
Milestone: omitted

What the experts said:

• ad-tech-protocol-expert: Slot-vs-instance distinction confirmed correct; Part B is a breaking TypeScript type change (semver major or documented minor needed); GroupBriefAssetSlotSchema/GroupCatalogAssetSlotSchema excluded from group union per spec
• code-reviewer: Part A is additive/non-breaking; hand-authored Zod companion file is the right approach (ts-to-zod can't handle GroupSlotOf<T> mapped types); changeset bump minor correct

My take: Part A (Zod slot schemas) is shipped as draft PR #1653. Part B (changing Format.assets from creative-instance types to FormatAssetSlot[]) needs a semver decision before it can be executed — both experts classify it as a breaking TypeScript type change. Tagging @bokelley to decide: (a) major bump, or (b) minor bump with documented breaking note.

What shipped in #1653: FormatAssetSlotSchema, IndividualAssetSlotSchema, RepeatableGroupSlotSchema, all 14 per-type individual slot schemas, 12 group slot schemas. Brief/catalog excluded from the group union per spec (matching RepeatableGroupAssetSchema).

What remains:

1. Part B — Tighten Format.assets typing in codegen (generate-types.ts string-replace post-processor); requires semver decision
2. Type/builder alignment — GroupAssetSlot TS type and briefGroupAsset/catalogGroupAsset builders in format-asset-slots.ts still include brief/catalog; aligning them is a breaking change (same semver decision as Part B)

---

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

---

Generated by Claude Code