Placement structure discriminator. publisher_ref identifies a placement by {publisher_domain, placement_id} and resolves public metadata from the named publisher's adagents.json placement declarations; seller_inline identifies buyer-facing placement metadata defined inline by the sales agent (still in the named publisher namespace when publisher_domain is present, or the seller's own namespace in legacy single-publisher contexts).
Placement identifier in the publisher namespace. When publisher_domain is present, this matches a placement ID in that publisher's adagents.json catalog or a seller-defined inline placement in that publisher namespace. Buyers use this with publisher_domain in creative_assignments[].placement_refs; legacy creative_assignments[].placement_ids strings are only unambiguous in single-publisher contexts.
Optionalpublisher_domain?: stringPublisher domain whose adagents.json placement declarations define this placement. Required for kind: "publisher_ref". Omitted only for kind: "seller_inline" in legacy single-publisher seller contexts where the seller agent's own publisher domain is the namespace.
Optionalname?: stringHuman-readable name for the placement (e.g., 'Homepage Banner', 'Article Sidebar'). Required for kind: "seller_inline". May be omitted for publisher-referenced placements because buyers resolve the name from the publisher declaration identified by {publisher_domain, placement_id}.
Optionaldescription?: stringDetailed description of where and how the placement appears
Required product-level relationship to this placement. targetable means the buyer may include the publisher-scoped ref in targeting_overlay.placement_selection; a creative may be routed there only after it is purchased. included means fixed product inventory: it cannot be independently selected, but across discovery, create, and update a selected request exactly equal to the product's complete included placement set is an inherent restatement and may be echoed on the package without overlay_support.placement_selection. A product containing any included placement MUST NOT declare overlay_support.placement_selection; partial selection requires a separately selectable product configuration. During the migration window ending 2026-11-25, buyers MAY tolerate legacy products that omit mode and treat them as targetable; after that date buyers SHOULD fail closed.
Optionaltags?: string[]Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope.
Optionalformat_ids?: [Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format placement narrowing. Can include concrete, template, or parameterized format IDs. When present on a product placement, this field narrows the product-level format_ids contract and MUST NOT introduce formats the product does not accept. Use canonical format_options.
Optionalformat_options?: [ProductFormatDeclaration, ...ProductFormatDeclaration[]]Canonical seller-side narrowing for this product placement. When present, these declarations are intersected with the product-level format_options and MUST NOT introduce a format outside that product upper bound. For kind publisher_ref, buyers MUST also resolve {publisher_domain, placement_id} in the publisher's adagents.json and intersect the publisher catalog constraint: use the public placement's format_options when present (resolving bare format_option_id references against same-file top-level formats[]), otherwise use applicable top-level formats[] scoped to that placement's properties. Omitting this inline field removes only the seller-inline layer; it does not bypass a publisher placement or property-scoped narrowing. The placement inherits the full product-level set only when no applicable publisher catalog narrowing exists. Unresolved publisher placement or format-option references fail closed. Locale policy participates in the same intersection: when the product policy is absent, a placement may introduce any concrete policy as a narrowing of the unconstrained option; when both are present, every placement accepted_language_range must be contained by a product range under RFC 4647 Basic Filtering (fr-CA narrows fr; fr does not narrow fr-CA). Buyers compute effective locale eligibility independently for each placement. Any effective locale-constrained route is canonical-only and has no projecting product or placement format_id.
Optionalvideo_placement_types?: [VideoPlacementType, ...VideoPlacementType[]]Declared video placement types for this product placement, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalaudio_distribution_types?: [AudioDistributionType, ...AudioDistributionType[]]Declared audio distribution types for this product placement, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalsponsored_placement_types?: [SponsoredPlacementType, ...SponsoredPlacementType[]]Declared sponsored-placement types for this product placement, distinguishing where the catalog-driven retail-media placement renders on the retailer surface. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalsocial_placement_surfaces?: [SocialPlacementSurface, ...SocialPlacementSurface[]]Declared social-placement surfaces for this product placement, distinguishing the in-app surface where the social placement renders. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Placement structure discriminator. publisher_ref identifies a placement by {publisher_domain, placement_id} and resolves public metadata from the named publisher's adagents.json placement declarations; seller_inline identifies buyer-facing placement metadata defined inline by the sales agent (still in the named publisher namespace when publisher_domain is present, or the seller's own namespace in legacy single-publisher contexts).
Placement identifier in the publisher namespace. When publisher_domain is present, this matches a placement ID in that publisher's adagents.json catalog or a seller-defined inline placement in that publisher namespace. Buyers use this with publisher_domain in creative_assignments[].placement_refs; legacy creative_assignments[].placement_ids strings are only unambiguous in single-publisher contexts.
Optionalpublisher_domain?: stringPublisher domain whose adagents.json placement declarations define this placement. Required for kind: "publisher_ref". Omitted only for kind: "seller_inline" in legacy single-publisher seller contexts where the seller agent's own publisher domain is the namespace.
Optionalname?: stringHuman-readable name for the placement (e.g., 'Homepage Banner', 'Article Sidebar'). Required for kind: "seller_inline". May be omitted for publisher-referenced placements because buyers resolve the name from the publisher declaration identified by {publisher_domain, placement_id}.
Optionaldescription?: stringDetailed description of where and how the placement appears
Required product-level relationship to this placement. targetable means the buyer may include the publisher-scoped ref in targeting_overlay.placement_selection; a creative may be routed there only after it is purchased. included means fixed product inventory: it cannot be independently selected, but across discovery, create, and update a selected request exactly equal to the product's complete included placement set is an inherent restatement and may be echoed on the package without overlay_support.placement_selection. A product containing any included placement MUST NOT declare overlay_support.placement_selection; partial selection requires a separately selectable product configuration. During the migration window ending 2026-11-25, buyers MAY tolerate legacy products that omit mode and treat them as targetable; after that date buyers SHOULD fail closed.
Optionaltags?: string[]Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope.
Optionalformat_ids?: [Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format placement narrowing. Can include concrete, template, or parameterized format IDs. When present on a product placement, this field narrows the product-level format_ids contract and MUST NOT introduce formats the product does not accept. Use canonical format_options.
Optionalformat_options?: [ProductFormatDeclaration, ...ProductFormatDeclaration[]]Canonical seller-side narrowing for this product placement. When present, these declarations are intersected with the product-level format_options and MUST NOT introduce a format outside that product upper bound. For kind publisher_ref, buyers MUST also resolve {publisher_domain, placement_id} in the publisher's adagents.json and intersect the publisher catalog constraint: use the public placement's format_options when present (resolving bare format_option_id references against same-file top-level formats[]), otherwise use applicable top-level formats[] scoped to that placement's properties. Omitting this inline field removes only the seller-inline layer; it does not bypass a publisher placement or property-scoped narrowing. The placement inherits the full product-level set only when no applicable publisher catalog narrowing exists. Unresolved publisher placement or format-option references fail closed. Locale policy participates in the same intersection: when the product policy is absent, a placement may introduce any concrete policy as a narrowing of the unconstrained option; when both are present, every placement accepted_language_range must be contained by a product range under RFC 4647 Basic Filtering (fr-CA narrows fr; fr does not narrow fr-CA). Buyers compute effective locale eligibility independently for each placement. Any effective locale-constrained route is canonical-only and has no projecting product or placement format_id.
Optionalvideo_placement_types?: [VideoPlacementType, ...VideoPlacementType[]]Declared video placement types for this product placement, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalaudio_distribution_types?: [AudioDistributionType, ...AudioDistributionType[]]Declared audio distribution types for this product placement, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalsponsored_placement_types?: [SponsoredPlacementType, ...SponsoredPlacementType[]]Declared sponsored-placement types for this product placement, distinguishing where the catalog-driven retail-media placement renders on the retailer surface. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Optionalsocial_placement_surfaces?: [SocialPlacementSurface, ...SocialPlacementSurface[]]Declared social-placement surfaces for this product placement, distinguishing the in-app surface where the social placement renders. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.
Represents a specific public ad placement within a product's inventory. Placement IDs are scoped by publisher domain, matching placement definitions in that publisher's adagents.json.
kindis the structural discriminator:publisher_refmeans this product placement is a reference to{publisher_domain, placement_id};seller_inlinemeans the seller is defining public buyer-facing placement metadata inline. The schema accepts eithernameorpublisher_domainbecause publisher-referenced placements can omitnameonly when the publisher declaration supplies it; seller-inline placements carrynamedirectly. Whether a reference was resolved from publisher-hosted adagents.json or a community-maintained fallback is resolver metadata, not placement structure. Placement selection purchases inventory; creative assignments may then route creatives only within the purchased set. Reusing a registered placement preserves the registry's semantic identity; product-level placement objects may narrow format_ids/format_options or add operational detail, but SHOULD NOT redefine the placement's meaning incompatibly.