Publisher-declared formats vs agent-deliverable formats: list_creative_formats(publisher_domain) returns a superset no single agent can fulfil

[bokelley]

Summary

#4620 made the publisher's adagents.json catalog the authoritative answer to "what formats does this property support." Implementing the consumer side surfaced a gap that #4620 didn't need to resolve: a publisher-declared format is not necessarily a format any authorized sales agent can actually deliver, and the protocol has no way to express the difference.

I don't see a mechanism for this today — if one exists, point me at it and this becomes a docs ask rather than a spec one.

The gap

Two different questions get the same answer shape:

• adagents.json#/formats[] — the publisher declares this unit exists and is sellable. Canonical format_kind + params, property-scoped via applies_to_property_ids / applies_to_property_tags, optionally bound to placements.
• What a sales agent can execute — this can physically traffic. Determined by the agent's ad server: the placements it has access to, and the creative types those placements accept.

These diverge routinely, in both directions:

• A publisher declares a seller-built multi-state unit (the spec(creative): add multi_state_display and page_takeover canonical formats (premium web display) #5972 category). The agent selling that publisher's inventory reaches it through an ad server with no execution path for it — no placement, no creative template, no rendering integration. The publisher is telling the truth; the agent still cannot sell it.
• An ad-server placement accepts a size or creative type the publisher never declared. Trafficable, undeclared.
• One publisher, several authorized agents, different ad-server footprints — so the deliverable subset differs per agent, while the declared set is shared.

Why it bites

1. A buyer resolving list_creative_formats(publisher_domain=...) gets a superset of what any one agent can fulfil. The failure shows up late — a rejected create_media_buy, or a creative that validates against the declaration and then has nowhere to serve.
2. The safe agent-side workaround defeats Property-scoped format declarations — authoritative source for 'what formats does <property> support' #4620. If agents defensively omit publisher-declared formats they can't execute and re-declare only their own product-inline format_options[], we are back to N copies of the same truth with drift — the exact problem Property-scoped format declarations — authoritative source for 'what formats does <property> support' #4620 set out to fix.
3. Multi-publisher products have no defined eligibility rule. A product spanning two publisher domains: is the eligible format set the union of their declared catalogs, or the intersection? The spec doesn't say, and the two readings are meaningfully different for a curator or network product. This one is answerable independently of everything else above, and probably should be.

Questions

Q1 — Multi-publisher eligibility (normative). Union or intersection for a product spanning multiple publisher domains? Placement-bound formats make this sharper: if placements[] binds formats to property_ids / property_tags, is eligibility computed at the property level and then unioned, or is the publisher-level catalog the unit?

Q2 — Who owns the deliverability delta? Three readings, and I'd like the WG to pick one rather than leave it to implementations:

• (a) Out of protocol scope. The publisher catalog is advisory — "what exists" — and the purchasable set is whatever appears in a product's format_options[]. Cheap, and mostly matches what implementations will do anyway, but it needs to be stated normatively in the docs, because Property-scoped format declarations — authoritative source for 'what formats does <property> support' #4620's framing ("authoritative source") reads as purchasable today.
• (b) Declare it per agent in adagents.json. An authorized_agents[] entry carries a supported/unsupported format subset. Keeps one file authoritative; makes the publisher responsible for maintaining facts about someone else's ad server, which seems wrong.
• (c) Report it agent-side. list_creative_formats responses distinguish publisher-declared from sellable-by-this-agent, so the agent answers for its own capability and the publisher still owns the declaration.

My read is (a) + (c): make the advisory/purchasable boundary normative in docs, and give the agent-side response enough provenance that a buyer agent can tell "the publisher says this exists" from "I can sell you this." That keeps the catalog authoritative for what it's genuinely authoritative about, and puts deliverability with the party that knows it.

Q3 — Provenance on format results. Related to (c) and useful regardless: should list_creative_formats results carry where each entry came from — publisher-hosted adagents.json, AAO mirror, or agent/product declaration? #4620 specced the resolution order (publisher-hosted → AAO mirror → fail-closed) but the result doesn't say which rung answered. A buyer treating a community-mirrored catalog the same as a publisher-hosted one is trusting a different thing.

Two smaller asks from the same implementation

Commercial terms are not format facts. Encoding a premium publisher's spec sheets, the material that most wanted to end up in the format schema was commercial: creative lead times, swap limits, approval SLAs. Those belong at product/negotiation level — they change per deal, and baking them into a format declaration laminates one seller's current manual process into a structural contract buyers validate against. Encoders reach for the format schema because it is the only structured place on offer. Worth a normative "format declarations describe the creative, not the terms of trade" line in the canonical-formats docs.

Classification convergence. Two independent expert encodings of the same publisher's spec material, by people who knew the spec, initially disagreed: one misclassification (a docking-video unit encoded as custom when its buyer deliverable was plain video_hosted), two source conflicts silently resolved in opposite directions, one format missed entirely. #5972 §5 documents the two boundaries that matter (multi_state_display vs responsive_creative; anything tag-delivered is display_tag regardless of behavioral richness) in prose, which is necessary and not sufficient — prose guidance did not converge two experts. Worth conformance fixtures: a set of realistic publisher spec descriptions with their expected canonical classification, so independent encoders and codegen consumers can check themselves. #4591 (conformance storyboard track) is closed — is there a home for classification fixtures, or should that be its own issue?

If classification stays this divergent, the catalog's authority erodes for a subtler reason than deliverability: two agents encode the same publisher unit two ways, and buyers can't tell it's the same unit.

Related

• Property-scoped format declarations — authoritative source for 'what formats does <property> support' #4620 — property-scoped format declarations; established the publisher catalog as authoritative (this issue is the deliverability follow-on)
• spec(creative): add multi_state_display and page_takeover canonical formats (premium web display) #5972 — multi_state_display / page_takeover; the format category where declared-but-not-trafficable is most common
• RFC: Publisher placement catalog, placement visibility, and product targetability #4993 — publisher placement catalog, placement visibility, product targetability
• placements-2.0: structured placement model (4.0 track) #5286 — placements-2.0 structured placement model (4.0 track); Q1's eligibility rule may want to land there
• Tracking: format_shape registry → canonical promotion queue (multi-placement takeover, roadblock, branded content, etc.) #3666 — format_shape → canonical promotion queue

[bokelley]

Triage

Classification: Spec question / RFC
Bucket(s): spec / protocol, creative, registry / discovery
Status: ready-for-human
Milestone: Spec Backlog

What the experts said:

• ad-tech-protocol-expert: Gap is structurally confirmed — authorized-agent-base.json has no format-scoping fields, so two conformant agents on the same publisher can each expose different format_options[] while the full set appears in adagents.json#/formats[], producing a wire-level create_media_buy rejection; (a)+(c) is the right split; option (c) must be sequenced before PR docs: document creative format discovery deprecation #5853 merges — once that PR lands without it, the only remaining surface for per-agent deliverability disappears from the protocol; Q1 (intersection) is operationally correct but needs a normative WG statement.
• adtech-product-expert: The two-layer design is already correct in the schemas — format_options[] is normatively the closed executable set, formats[] is advisory capacity declaration — the problem is documentation not saying this; option (b) is operationally infeasible (publishers cannot maintain agent ad-server capability lists); option (c) becomes time-bounded once docs: document creative format discovery deprecation #5853 lands; recommend two targeted doc patches in the current cycle and a separate follow-on issue for Q1.

My take: Experts agree on (a)+(c) and unanimously reject (b). Q2's docs patch ((a)) is patch-eligible and can ship now; Q3's provenance field ((c)) has a hard sequencing dependency on PR #5853 that needs a human decision before that PR merges; Q1 (multi-publisher eligibility) is a pure WG policy call with real implementation consequences.

---

Q1 — Multi-publisher format eligibility (WG vote needed)

The publisher_properties authorization type in adagents.json already supports multi-publisher entries but carries no eligibility composition rule.

Option — Union (formats declared by any publisher in the product span):

// Product spans publisher_a.com + publisher_b.com
// Eligible = union of both declared catalogs
// Risk: buyer requests a format only one publisher supports; the other can't execute
{ "note": "wider inventory surface, late rejection risk per publisher" }

Option — Intersection (formats declared by all publishers in span):

// Eligible = only formats declared by EVERY publisher in the product
// Risk: sparse overlap may produce an empty set for broad network products
{ "note": "guaranteed common ground, narrower surface" }

Both experts read the schema as silent. Protocol expert considers intersection operationally correct; product expert defers to WG. Placement-bound formats (via applies_to_property_ids / applies_to_property_tags) make this sharper: eligibility may need to be computed at property level and then composed. This can be filed as a targeted follow-on once the composition rule is decided — likely touches #5286 (placements-2.0, 4.0 track).

---

Q2 — Deliverability delta: two-part answer, one item needing sequencing decision

Part (a) — Normative docs clarification (patch-eligible, no wire change, ready now):

 // adagents.json formats[] description — proposed addition to docs
-"Authoritative source of which formats this publisher's inventory supports"
+"Publisher capacity declaration (advisory — what the publisher accepts for its inventory).
+ The purchasable/executable set for any given agent is format_options[] on Product,
+ which MUST be treated as the normative closed set for create_media_buy."

Both experts endorse this. Resolves the "authoritative source" framing from #4620 without changing any wire behavior. Also covers the commercial-terms ask: add a SHOULD NOT in the same docs section — format declarations describe creative specs, not terms of trade.

Part (c) — Provenance field on list_creative_formats response (additive, minor bump, sequencing call):

// list_creative_formats response entry — proposed optional field
{
  "format_kind": "video_hosted",
  "params": { "duration_max_seconds": 30 },
  "provenance": "publisher_declared"
  // optional enum: "publisher_declared" | "agent_deliverable" | "both"
}

Must land before PR #5853 merges, or the surface that can carry per-agent deliverability disappears. If #5853 lands first, new integrations route to get_products.format_options[] (purchasable by construction) and get_adcp_capabilities.creative.supported_formats (agent-scoped), making (c) only relevant for the deprecated path. @bokelley: should (c) be scoped into #5853 / coordinated before it merges, or is the deprecated-path window acceptable?

Option (b) — rejected by both experts: publishers cannot maintain agent ad-server capability data; enforcement gate is already format_options[] on Product.

---

Two smaller asks:

• Commercial terms: Covered by the (a) docs patch above — one normative line. No schema change.
• Classification conformance fixtures: Both experts recommend a separate issue. The divergence is real but not blocking format-catalog authority. Not worth scope here.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

Two additions from continuing the consumer-side implementation, both narrower than the main ask above.

placements[] is missing from the publisher lookup projection

GET /api/registry/publisher (PublisherLookupResult) is the natural single read for a consumer building publisher-scoped format eligibility: it proxies the origin crawl (hosting.mode, last_http_status, last_validated, resolved_url, on-demand auto_crawl_triggered), unifies publisher-hosted and community catalogs behind one shape (files.adagents_json.status: valid | community | invalid | ..., discovery_method: community_catalog, per-property source), and already projects formats[] with format_kind, params, format_option_id, and the applies_to_property_ids / applies_to_property_tags scoping.

It does not project placements[]. Those appear only in the POST /api/adagents/create request shape and in CommunityMirrorGetResponse → CommunityMirrorAdagentsJson.

That matters because placements are the eligibility join. AdagentsPlacementDefinition binds property_ids / property_tags → format_options[] (inline declaration or format_option_id reference into top-level formats[]). Without them, a consumer can answer "what formats does this publisher declare, scoped to this property" but not "what formats are reachable from the placements that actually exist on this property" — which is the question a seller-side product builder or a buyer narrowing a package needs answered. Today that forces a second read of the raw document per domain, which reintroduces exactly the per-origin fetch the lookup exists to avoid.

Request: project placements[] onto PublisherLookupResult, alongside the existing formats[] and properties[].

The lookup's formats[] is lossy in a way worth documenting (or making optional)

The field is described as a "display-oriented summary of top-level adagents.json formats[], normalized for publisher pages and agent discovery clients." It preserves format_kind, format_option_id, params, and the applies_to_* scoping — but drops v1_format_ref and canonical_formats_only.

That's the right default for a publisher page. It's not sufficient for creative validation, where a consumer needs the full ProductFormatDeclaration including the v1 projection refs. Right now the only way to tell you need a second read is to notice the fields are absent.

Two options, either is fine:

• Document the projection as lossy and name what it drops, so consumers know when to fetch the canonical document instead.
• Add an opt-in (?formats=full or equivalent) that returns the unprojected declarations.

Related to the main issue

Both of these compound the deliverability question above. A consumer assembling "what can I actually sell on this property" wants, in one read: the declared formats, the placements that reach them, the provenance of each (publisher origin vs community catalog — different trust levels), and ideally the agent-side deliverability delta. The first is there today, the second is missing, the third is present and good (source / discovery_method / hosting.mode), and the fourth is what this issue asks for.

[bokelley]

Two more from the same implementation pass. The first is a question I can't answer from the schema; the second is an implementer trap I walked into myself.

Q4 — Does publisher.adagents_changed cover a formats-only or placements-only revision, and can a consumer tell?

A consumer keeping a publisher catalog fresh routes the feed on publisher_domain and re-reads on change. Two things are unclear:

Trigger coverage. Does publisher.adagents_changed fire when a crawl finds the document changed only in formats[] or placements[] — no property, agent, or collection delta? The event name suggests document-level change detection, which would cover it. But PublisherEventPayload counts only properties_added, properties_removed, agents_added, agents_removed, agent_count, property_count, collection_count — no format or placement counters. That's at least suggestive that the change detector is watching the property/agent/collection projections rather than the whole document. I can't tell which from the schema, and the answer decides whether catalog consumers need an independent re-resolve floor.

This matters for the concrete case the publisher catalog exists to serve: a publisher revises a spec sheet, video duration goes 15s → 30s, they update formats[], nothing else in the file moves. If that doesn't emit, every consumer's cached format view is silently stale until an unrelated edit happens to touch a property.

Payload observability. Even when it does fire, the payload can't say what changed in the catalog. A consumer can't distinguish "formats unchanged" from "formats not tracked," so the only safe behavior is to refetch and diff everything on every publisher.* event.

Two asks, in order of preference:

• Confirm (and document) that the trigger is whole-document, so consumers can rely on publisher.adagents_changed for catalog freshness.
• Add format_count / placement_count to PublisherEventPayload — or better, a changed_sections: ["formats", "placements"] list — so a consumer can route and diff without a blind full refetch per event.

The discovery validator can't see community catalogs, and #4620's resolution order implies it can

#4620 specced the resolution order for "what formats does this publisher support" as publisher-hosted adagents.json → AAO mirror → fail-closed.

The SDK has two paths that both look like they implement that, and only one does:

• validateAdAgents() (discovery layer) resolves direct → authoritative_location → ads_txt_managerdomain. No community-catalog rung. A publisher with no self-hosted file returns not-found, full stop.
• RegistryClient.lookupPublisher() surfaces discovery_method: community_catalog and files.adagents_json.status: "community" with a registry_url, alongside per-property source: adagents_json | community | discovered | brand_json.

So an implementer who reads #4620, reaches for the discovery-layer validator because it is the thing named validateAdAgents, and implements the specced order on top of it will silently miss every community catalog — which is to say, every walled garden, which is to say the majority of the format declarations that exist today. The failure is quiet: the fetch succeeds in reporting "no file," and the mirror rung never gets consulted.

I did exactly this earlier today before being corrected, which is why I think it's worth a docs fix rather than assuming it's obvious.

Ask: state in the resolution-order docs that the mirror rung is served by the registry API (GET /api/registry/publisher), not by the discovery-layer validator, and that a consumer wanting the full specced order should read the registry lookup rather than composing it from validateAdAgents. If the intent is that the discovery layer eventually gains the mirror fallback, saying so is equally useful — then the guidance is "not yet, use the registry."

Adjacent to Q3 above: this is the same provenance concern from the other end. A consumer that reads only the origin gets a narrower view than the spec promises; one that reads the registry gets the full view but must then distinguish publisher-asserted from community-contributed, which source / discovery_method / hosting.mode do well already.

[bokelley]

Triage — follow-up (2026-07-30 comment)

Classification: Feature request / Spec question
Bucket(s): registry / discovery, spec / protocol, web / site / docs
Status: partial-ready — Ask 1 ready-for-human (shape decision); Ask 2a ready-to-implement; Ask 2b deferred

Covers the two narrower asks from the follow-up comment. Prior triage above (Q1/Q2/Q3, sequencing question on #5853) stands unchanged.

What the experts said:

• ad-tech-protocol-expert: Adding placements[] as raw passthrough (AdagentsCatalogItemSchema) is non-breaking and structurally parallel to CommunityMirrorAdagentsJson — ready to implement; Option A (document the projection) is non-breaking docs-only — ready now; Option B needs a naming-convention decision before shipping — prefers ?projection=full as a uniform selector covering formats + placements + properties in one parameter.
• adtech-product-expert: Raw placements[] passthrough is too heavy for large publishers (inline ProductFormatDeclaration within format_options[] makes large-publisher responses unwieldy); community-catalog placement_id values used in creative_assignments[].placement_refs carry lower trust than publisher-hosted ones and must be machine-detectable per-row — may be WG-scope; Option A ships now; Option B premature until an integrator demonstrates hosting.expected_url doesn't work as the creative-validation fallback.

My take: Experts converge on Ask 2a (docs). Split on Ask 1 implementation shape; product expert's community-trust concern on placement IDs is substantive and needs a human call before implementation. Ask 2b needs a naming-convention decision first.

---

Ask 1 — placements[] missing from PublisherLookupResult: ready-for-human (shape decision)

Both experts confirm: gap is real, addition is non-breaking, eligibility-join use case is legitimate. They split on shape:

Option — Raw passthrough (parallel to CommunityMirrorAdagentsJson):

// PublisherLookupResult — minimal Zod addition: z.array(AdagentsCatalogItemSchema).optional()
{
  "placements": [
    {
      "placement_id": "home_banner",
      "property_ids": ["site_home"],
      "format_options": [{ "format_option_id": "display_300x250" }]
    }
  ]
  // format_option_id refs resolve against top-level formats[] in same response
}

One-line Zod change; exact precedent in CommunityMirrorAdagentsJson. Inline format specs inside placement format_options[] pass through untyped — acceptable under existing precedent, but large publishers produce big payloads.

Option — PublisherPlacementSummarySchema (parallel to PublisherFormatSummarySchema):

// Compact projection — new summarizePlacements() function + source labeling
{
  "placements": [
    {
      "placement_id": "home_banner",
      "name": "Homepage Banner",
      "property_ids": ["site_home"],
      "property_tags": [],
      "channels": ["display"],
      "format_option_ids": ["display_300x250"],
      "source": "adagents_json"   // | "community"
    }
  ]
  // format_option_ids are references into top-level formats[]; no inline declarations
}

Cap-able and consistent with how formats[] handles the same problem. source: "community" lets consumers flag lower-trust placement IDs before using them in creative_assignments[].placement_refs. Implementation cost: moderate (new summary function + source-labeling logic).

@bokelley: which shape? The community-placement trust question in creative_assignments[] may be WG-scope regardless — if a stale or misattributed community placement_id reaches creative_assignments, the failure is at serve-time, not discovery-time. The summary option exposes this risk earlier; the passthrough option defers it.

---

Ask 2a — Document the lossy formats[] projection: ready to implement

Both experts agree. Additional note: more fields are dropped than the comment names. The full omission list from ProductFormatDeclaration: v1_format_ref, canonical_formats_only, applies_to_channels, publisher_domain; for custom formats also format_shape and format_schema. The applies_to_channels omission is the most dangerous operationally — a buyer agent selecting a format for a multi-channel product has no channel-scoping signal and may silently pick a video-only format for a display placement.

Implementation scope (docs-only, no changeset):

• server/src/schemas/registry.ts lines 1072–1074 — one sentence to the formats field description naming all omitted fields and pointing to hosting.expected_url (or hosting.resolved_url) for creative-validation consumers
• static/openapi/registry.yaml line 1193 — same addition in OpenAPI description

---

Ask 2b — ?formats=full opt-in: deferred (naming convention first)

Both experts flag ?formats=full as the wrong name. Protocol expert: ?projection=full (or equivalent) as a uniform depth selector across formats, placements, and properties in one additive PR is the right shape. Product expert: defer until an integrator shows hosting.expected_url doesn't cover the creative-validation case. If Ask 1 lands and placements need a depth selector too, the naming question is the same one — worth deciding once.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code