Build-time input-slot vocabulary: allowed_values, suggested_values, language, repeatable input groups, external-reference inputs

[bokelley]

Context

This issue proposes additions to the build-time input-slot side of the creative protocol — distinct from the canonical output formats. The motivation is that as creative agents proliferate (Figma wrappers, Canva wrappers, AI generators, custom HTML renderers), they all need to advertise what inputs they accept in a way that an upstream orchestrator (or a buyer) can target generically.

This is largely a comment on #3305 (Creative Formats v2 RFC) — where build inputs collapse onto format declarations and validate_input becomes the dry-run primitive. A subset is small enough to land additively in 3.1 ahead of the full v2 redesign.

The framing throughout: canonical formats describe the output contract (PNG/HTML/MP4 the seller will accept and how it tracks); input-slot declarations describe the build-time contract (what the creative agent needs to fill in to produce that output). They live at different layers and shouldn't bleed.

Motivating example

A generic Figma-MCP wrapper exposes each Figma frame as a creative agent capability. Frame named meta_1080x1080, with named layers HEADLINE, SUBLINE, CTA, HERO_IMAGE, LOGO. The wrapper renders to a canonical image output, but its input-slot declaration needs to say:

• HEADLINE: text, max 60 chars, language en (or nl-NL etc. per file)
• CTA: text, must be one of ["Apply now", "View job", "Solliciteer direct"]
• HERO_IMAGE: image, ≥1080×1080 — accepts a URL or a reference into a published asset library

The orchestrator (or a buyer) calls validate_input with proposed values, gets back valid: true/false plus per-slot errors, then calls the build primitive. Today there's no place in the protocol to express the picker, the language, or the catalog reference.

Proposed additions

1. allowed_values on text input slots — 3.1 candidate

Additive on text-asset-requirements.json. Closed enum of permitted strings. Validated by validate_input.

{
  "asset_type": "text",
  "asset_role": "cta",
  "max_length": 30,
  "allowed_values": ["Apply now", "View job", "Solliciteer direct"]
}

2. suggested_values on text input slots — v2 RFC

Open hint list. Discoverable by orchestrators that want to pick from a creative-agent-supplied template library; humans can override. Distinct from allowed_values (closed) so the validation semantics are clear.

{
  "asset_type": "text",
  "asset_role": "headline",
  "max_length": 60,
  "suggested_values": [
    "Werken als {{role}} bij {{brand}} {{location}}",
    "{{role}} gezocht in {{location}}"
  ]
}

(Whether suggested_values should support placeholders like {{role}} is a follow-on question — could just be plain strings the orchestrator template-fills before submitting.)

3. language on input slots — 3.1 candidate

The manifest-side text asset already carries language. Mirroring it on the input-slot requirements lets a creative agent declare per-slot locales (e.g., a Dutch-only Figma file declares language: "nl-NL" on every text slot), and validate_input can reject mismatched submissions early.

4. Repeatable input groups — v2 RFC

The output side already has item_type: "repeatable_group" (carousels, slideshows). The input side has no equivalent. The recruitment-SEA case wants "15 headline inputs + 4 description inputs"; today this has to be modeled as 15 individual slots, which doesn't compose. Proposing symmetry: an item_type: "repeatable_group" input that wraps a slot template plus min_count/max_count.

5. External-reference input slots — v2 RFC

An input slot that says: "I accept a URL, or a reference into this catalog/library." This is the clean answer to the per-location-photography pattern that today gets wedged into brand.json: photos live in a separately addressable asset library, and the hero_image input slot declares it accepts references into that library.

{
  "asset_type": "image",
  "asset_role": "hero_image",
  "min_width": 1080,
  "accepts_reference": {
    "schema": "https://example.com/photo-library.json",
    "selector": "$.locations[?(@.id == $location_id)].photography.exterior[*]"
  }
}

This intentionally does not put the catalog in brand.json — the v2 RFC's "brand.json with override capability" framing is preserved. The catalog is its own document that input slots can target.

Status of overlap with #3305

• validate_input (already scaffolded in RFC #3305 implementation preview — v2 creative formats (full spec, not for merge) #3307): the natural validation surface for all five.
• Canonical asset-group vocabulary (already shipped in RFC #3305 implementation preview — v2 creative formats (full spec, not for merge) #3307): orthogonal — these proposals add constraints on slot fills, not new slot roles.
• format_id becoming a string: orthogonal.
• brand.json with override capability: (5) is the cleanest answer to the "where does catalog data live" question that I think the override design is also trying to solve.

Suggested split

• 3.1 (additive on text-asset-requirements.json): (1) allowed_values, (3) language.
• v2 RFC discussion (RFC: Creative Formats v2 — canonical formats live on products, composition primitives, validate_input #3305): (2) suggested_values, (4) repeatable input groups, (5) external-reference inputs.

Happy to break (1) and (3) into a separate small PR if that helps land them sooner.

Notes

• The example in (5) uses JSONPath in selector — that's a sketch, not a recommendation. The real design probably wants something simpler (or a more constrained pointer scheme); that's a discussion to have if the idea has legs.
• asset_role: "cta" / "headline" / "hero_image" assume the canonical asset-group vocabulary from RFC #3305 implementation preview — v2 creative formats (full spec, not for merge) #3307 covers these. If it doesn't yet, the proposal still stands but the role names would shift.

[bokelley]

Triage

Classification: Feature request (mixed — 3.1 candidates + v2 RFC items)
Bucket(s): spec / protocol, creative, schema
Status: drafting-pr (items 1, 3 split: item 1 executing; item 3 ready-for-human); deferred (items 2, 4, 5 — blocked on #3305)
Milestone: 3.1.0 (items 1 and 3 only; items 2, 4, 5 are v2 RFC scope)

What the experts said:

• ad-tech-protocol-expert: allowed_values is sound and consistent with feature-requirement.json precedent; uniqueItems: true and minItems: 1 both correct. language at slot-grain is protocol-valid if BCP 47 is used, but the codebase has four competing language-code conventions — adding a slot-level field without resolving which convention applies creates a validate_input conformance gap.
• adtech-product-expert: allowed_values is a real workflow need for DCO/generative pipelines; template-string semantics must be MUST-deferred, not SHOULD. language grain is wrong at slot level — a whole-format language on format.json is the right home, with slot-level as override-only; per-slot repetition creates noise for single-locale templates.

Item 1 — allowed_values: drafting PR #4333.
Additive optional field on text-asset-requirements.json; non-breaking. Two reviewer passes resolved all blockers (case-sensitivity MUST, template-token deferral MUST, uniqueItems: true, implementation-agnostic normative phrasing).

Item 3 — language: expert split on grain — @bokelley, your call:

Option A — slot-level (author's proposal):

// text-asset-requirements.json — per slot
{
  "asset_type": "text",
  "asset_role": "cta",
  "max_length": 30,
  "language": "nl-NL"
}

Protocol expert: BCP 47 pattern required; validate_input semantics (what if language absent on submitted asset?) need normative language. Slot-level is the right surface for per-slot overrides.

Option B — format-level (product expert recommendation):

// format.json — one field, whole format
{
  "format_id": "meta_1080x1080",
  "language": "nl-NL",
  "inputs": [
    { "asset_id": "CTA", "asset_type": "text", "max_length": 30 }
  ]
}

Product expert: operators will repeat the same code on every slot or leave some blank inconsistently; format-level is where locale lives in TTD/DV360 practice. Slot-level survives only as an override field once the format-level canonical is established.

Items 2, 4, 5 — deferred: suggested_values, repeatable input groups, and external-reference inputs belong in the v2 RFC discussion.

Blocked-on: #3305 — resurfaces on merge

---

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

---

Generated by Claude Code