Allow bare `min_duration_ms` / `max_duration_ms` on `video_hosted` and `audio_hosted` params

[bokelley]

Problem

video_hosted and audio_hosted can express an exact duration (duration_ms_exact) or a closed range (duration_ms_range: [min, max]), but not a single open bound — i.e. "up to N seconds" or "at least N seconds." The common real-world constraint is a ceiling ("≤30s audio," "≤60s video"), which today has nowhere clean to go: you must either fake an exact value or invent a lower bound ([0, 30000] / [1, 30000]), both of which misstate the contract.

Current state (3.1.0-rc.4)

• formats/canonical/video_hosted.json duration params: duration_ms_range, duration_ms_exact — no bare min/max.
• formats/canonical/audio_hosted.json duration params: duration_ms_range, duration_ms_exact — no bare min/max.
• formats/canonical/image_carousel.json already has a bare card_video_max_duration_ms — so the bare-max pattern is already blessed in one canonical; it's just inconsistent across the others.

Why this matters — evidence

Implementing the Spotify standard audio ad ("up to 30 seconds"), we had to publish it as duration_ms_exact: 30000 because a max-only "≤30s" had no field — overstating it as exactly 30s. The same gap hits social video caps (TikTok / Snap / Reels "up to N seconds").

Proposed change

Add optional min_duration_ms and max_duration_ms to video_hosted and audio_hosted params, alongside the existing duration_ms_range / duration_ms_exact, matching the bare-max precedent already in image_carousel.card_video_max_duration_ms.

Documented resolution precedence: duration_ms_exact (fixed) → duration_ms_range (closed) → bare min_duration_ms / max_duration_ms (open bound; either or both).

Affected files

• static/schemas/src/formats/canonical/video_hosted.json
• static/schemas/src/formats/canonical/audio_hosted.json
• docs/creative/canonical-formats.mdx — duration field precedence

What this is NOT

• Non-breaking: purely additive optional fields; existing duration_ms_exact / duration_ms_range unchanged.

Filed from implementer experience maintaining AdCP community-mirror catalogs.

[bokelley]

Triage

Classification: Feature request
Bucket(s): spec / protocol, creative
Status: ready-to-implement
Milestone: Spec Backlog

What the experts said:

• ad-tech-protocol-expert: Gap is real and well-evidenced; bare min_duration_ms / max_duration_ms is the right shape — the pattern already exists in three places in this repo (responsive_creative.json, core/requirements/video-asset-requirements.json, core/requirements/audio-asset-requirements.json) and mirrors OpenRTB 2.6 §3.2.7 minduration/maxduration. One spec-wording constraint: the description must say "applies only when duration_ms_exact and duration_ms_range are both absent" — not "lower priority than" — to prevent floor-conflict ambiguity when a range and bare bounds coexist on the same product. Non-breaking (purely additive under additionalProperties: true); minor changeset.
• adtech-product-expert: Implementer pain confirmed — Spotify ≤30s audio, TikTok/Snap/Reels short-form caps are all max-only in practice; creative agents branch meaningfully on "up to 30s" vs "exactly 30s," and the current workaround (duration_ms_exact: 30000) causes unnecessary creative rejections for shorter-but-valid spots. Recommends folding card_video_min_duration_ms into image_carousel.json in the same PR to close the parallel gap. SDK lint hint (warn when >1 duration constraint field is present) should be in the description text.

My take: Both experts agree: the gap is real, the field shape is correct (matches existing in-repo precedents), and the change is non-breaking. The one wording constraint matters — spec must frame bare bounds as "applies when the other fields are absent" so SDK authors cannot produce conflicting multi-field combinations silently.

Implementation scope:

• Add min_duration_ms and max_duration_ms (type: integer, minimum: 1, optional) to static/schemas/source/formats/canonical/video_hosted.json and audio_hosted.json params, matching the core/requirements/audio-asset-requirements.json field shape exactly
• Add card_video_min_duration_ms to static/schemas/source/formats/canonical/image_carousel.json to close the sibling gap while these schemas are already open
• Field descriptions must include: "Applies only when duration_ms_exact and duration_ms_range are both absent. SDKs SHOULD warn when more than one duration constraint field is present on the same product."
• Update docs/creative/canonical-formats.mdx with a duration precedence table and open-bound examples (≤30s audio, ≤60s video)
• Changeset: minor (new optional fields on stable surfaces — video_hosted, audio_hosted, image_carousel all lack x-status: experimental)
• Non-breaking: purely additive; no existing product declaration affected; zero adopter migration cost

---

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

---

Generated by Claude Code