Interface PackageRequest

Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.

DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.

Product ID for this package. Sellers MUST echo this value on every response package object that represents this requested package.

Legacy named-format selector. Array of format IDs that will be used for this package - must be supported by the product. If omitted (and no 3.1+ format-option selector or direct canonical selector is present), defaults to all formats supported by the product.

Sellers comparing this selector to a product's format_options[] MUST first normalize each legacy format_id through the canonical mapping path (canonical, v1_format_ref, or registry projection). Exact (agent_url, id) comparison after projection is insufficient: a legacy fixed-size display ID can satisfy a canonical image product declaration with matching width/height. Product gating remains directional: if the product declares fixed dimensions or duration, the selected format must declare and match those constraints; an under-specified canonical request is not a wildcard for a fixed-size or fixed-duration product. Range constraints use containment, not overlap: a range-based request satisfies the product only when every value it permits falls within the product's accepted range.

3.1+ format-option selector. Array of structured format option references, each matching one of the target product's format_options[] entries. Publisher-catalog-backed options match by { scope: "publisher", publisher_domain, format_option_id }; product-local options match by { scope: "product", format_option_id }. If omitted along with format_ids and direct format_kind, all product formats are active.

Resolution rules (normative).

• Both format_option_refs and format_ids present. format_option_refs wins; the seller routes by structured references and MUST NOT validate format_ids for consistency with the resolved declarations. The format_ids value is a legacy-compat hint for intermediaries on the wire path; the resolving seller ignores it.
• format_option_refs only. Seller looks up each entry against the package's target product format_options[] and uses the matching declaration (and that declaration's v1_format_ref[] when projecting to legacy named-format surfaces). This is the 3.1+ format-option authoring path. scope: "product" is scoped only by this target product; it is not a seller-wide identifier.
• format_ids only. Existing named-format behavior; unchanged.
• format_kind only. Direct canonical selector behavior; seller compares { format_kind, params } against the product's format_options[] declarations using directional product satisfaction.
• None of format_option_refs, format_ids, or format_kind. Default — all formats supported by the product are active.

Failure modes (normative). Sellers MUST reject with UNSUPPORTED_FEATURE (with field pointing at the failing package and entry, e.g. packages[0].format_option_refs[1]) when:

• Any entry references a format option not present in the target product's format_options[], OR
• The target product carries format_ids but no format_options[] (legacy-format-only product — there is no closed set to resolve against), OR
• The target product carries format_options[] but none of the entries publish selectable format_option_id values. Sellers SHOULD set error.details.reason to format_option_refs_not_published in this case so buyers can distinguish it from an outright mismatch and fall back to format_ids[].

Seller obligation. For buyers to use the 3.1+ format-option path against a product, the seller MUST publish a selectable format_option_id on each format_options[] entry it expects buyers to select; if the option is publisher-catalog backed, include publisher_domain on the product declaration and require buyers to use scope: "publisher" in FormatOptionRef.

No legacy capability selector. capability_ids was removed before GA; schemas reject it instead of treating it as an extension.

Dual emission. Format-option-aware buyer SDKs targeting a heterogeneous seller population SHOULD emit format_ids alongside format_option_refs so legacy-format-only sellers — which ignore unknown fields per additionalProperties: true — still receive an explicit format set rather than silently defaulting to all formats supported by the product.

Parameters for the direct canonical selector in format_kind. Shape follows the selected canonical's parameter vocabulary: dimensions (width, height, sizes), duration (duration_ms_exact, duration_ms_range), codecs, asset-source and slot narrowing, or other canonical-specific constraints. Omit when selecting by format_option_refs or format_ids; those selectors resolve their parameters from the product declaration or legacy catalog projection.

Budget allocation for this package in the media buy's currency

ID of the selected pricing option from the product's pricing_options array

Bid price for auction-based pricing options. This is the exact bid/price to honor unless selected pricing_option has max_bid=true, in which case bid_price is the buyer's maximum willingness to pay (ceiling).

Impression goal for this package

Flight start date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's start_time. Must fall within the media buy's date range.

Flight end date/time for this package in ISO 8601 format. When omitted, the package inherits the media buy's end_time. Must fall within the media buy's date range.

Whether this package should be created in a paused state. Paused packages do not deliver impressions. Defaults to false.

Catalogs this package promotes. Each catalog MUST have a distinct type (e.g., one product catalog, one store catalog). This constraint is enforced at the application level — sellers MUST reject requests containing multiple catalogs of the same type with a validation_error. Makes the package catalog-driven: one budget envelope, platform optimizes across items.

Optimization targets for this package. The seller optimizes delivery toward these goals in priority order. Common pattern: event goals (purchase, install) as primary targets at priority 1; metric goals (clicks, views) as secondary proxy signals at priority 2+.

Buyer's proposed performance standards for this package. Overrides product defaults. Seller accepts, rejects with TERMS_REJECTED, or adjusts. When absent, product's performance_standards apply.

Buyer's proposed reporting contract for this package — the metrics the buyer wants the seller to commit to populating in delivery reports. Same negotiation pattern as measurement_terms and performance_standards: seller accepts (echoes on confirmed package with committed_at stamped), rejects with TERMS_REJECTED (with explanation of which entries were unworkable), or normalizes (echoes a different but compatible list — buyer can accept by retrying with the normalized terms). When absent, the seller decides what to commit based on the product's available_metrics and the buyer's required_metrics filter on get_products. Each entry uses an explicit scope discriminator (standard or vendor) and identifies the metric — request-side entries do NOT carry committed_at; that timestamp is stamped by the seller on accept. Constraints on what the buyer MAY propose: each scope: standard entry's metric_id MUST be in the product's available_metrics, and each scope: vendor entry's (vendor, metric_id) MUST appear in the product's vendor_metrics — sellers SHOULD reject with TERMS_REJECTED and reference the offending entry when the proposal exceeds product capability.

Assign existing library creatives to this package with optional weights and placement targeting

Upload creative assets inline and assign to this package. When the seller also advertises creative.has_creative_library: true, these creatives enter the seller's creative library and can be reused by creative_id while retained; inline-only sellers may store them as package-scoped assets. Use creative_assignments instead for existing library creatives.

Agency estimate or authorization number for this package. Overrides the media buy-level estimate number when different packages correspond to different agency estimates (e.g., different stations or flights within the same buy).