Skip to content

spec: get_creative_delivery uses inline pagination.total while every other list response uses PaginationResponse.total_count #4584

@bokelley

Description

@bokelley

Context

Surfaced during @adcp/sdk bridge work (adcontextprotocol/adcp-client#1772). The protocol-expert review noted:

get_creative_delivery defines pagination inline with a total field while the rest of 3.0.11 uses PaginationResponse.total_count. The bridge correctly uses total — but this is inconsistent with the rest of the spec.

Evidence

  • schemas/cache/3.0.11/bundled/creative/get-creative-delivery-response.json line ~5519-5540 defines pagination INLINE as {has_more, cursor, total} (note the field name total, no _count)
  • schemas/cache/3.0.11/core/pagination-response.json is the shared PaginationResponse schema with fields {has_more, cursor, total_count}
  • Other list responses that use the shared schema via $ref:
    • list_creatives
    • get_signals
    • list_property_lists
    • list_collection_lists
    • list_content_standards
    • All consistently use total_count

get_creative_delivery is the only list response in 3.0.11 with the inline divergent shape.

Likely cause

Drafting drift. Probably an early-spec inline definition that was never refactored to $ref: PaginationResponse when the shared schema was introduced.

Suggested fix

Replace the inline pagination block in get-creative-delivery-response.json with:

"pagination": {
  "$ref": "../core/pagination-response.json"
}

This standardizes the field name (total_count everywhere) and reduces maintenance surface — pagination semantics live in one place.

Migration impact

Buyer-facing breaking change if any adopter has already implemented get_creative_delivery reading pagination.total. Worth a brief grep in adopter repos before the rename. Conservative alternative: keep total as an alias for one minor version, deprecate in changelog, remove in next major.

Adopter context

When the SDK implements pagination-drift recomputation in its bridge layer, every bridge has to know the right field name. Inconsistencies create per-tool special-casing that should be straight schema lookup. We worked around it for now (if (typeof pagination.total === 'number') instead of total_count), but the spec drift is the real fix.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions