{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.1.0-beta.2/core/asset-group-vocabulary.json",
  "title": "AdCP Asset Group Vocabulary Registry",
  "description": "Canonical registry of asset_group_id values used in offering asset groups (OfferingAssetGroup) and in v2 product format declarations. Non-canonical IDs remain valid for platform-specific extensions; this registry codifies the recommended canonical set so that buyers and sellers share a vocabulary for the most common slot roles. Validators may emit soft warnings on non-canonical IDs to encourage convergence.\n\nThe registry covers everything the buyer ships in the manifest's `assets` map — both directly-rendered creative content (image, video, audio) AND content the seller consumes for production (script, creative_brief, video_brief). The seller dispatches per the format's slot declaration. There is no separate \"inputs\" map on the manifest; everything is an asset.\n\n**Two-tier boundary (normative).** This registry is the *canonical, portable* tier — IAB-aligned, platform-agnostic slot roles every adopter shares (`headline`, `body_text`, `main_image`, `cta`, `landing_page_url`, etc.). Platform-specific asset identifiers (e.g., YouTube video IDs, Pinterest pin IDs, TikTok video IDs, Snap attachment IDs, Meta Advantage+ creative IDs) MUST NOT be added here — they live on the canonical's `platform_extensions[]` (URI+digest reference to the platform's extension schema) so the canonical registry stays portable. Earlier drafts carried `youtube_video_id` and `pin_id` here; they were dropped in 3.1 GA precisely because adding them set precedent for every platform's identifier vocabulary to leak into the canonical tier, defeating the registry's portability purpose. Adopters needing to reference an existing platform-hosted asset attach a `platform_extensions[]` entry on the format declaration whose extension schema defines the platform-specific ID slot.",
  "version": "1.1.0",
  "lastUpdated": "2026-04-28",
  "vocabulary": {
    "headlines": {
      "description": "Pool of headline text variants for the surface to choose from.",
      "asset_type": "text",
      "typical_use": "Multiple short headline copy variants (Google PMax/RDA, Meta promoted_offerings, etc.)",
      "aliases": ["headline", "title", "tagline", "headline_text"]
    },
    "long_headlines": {
      "description": "Pool of longer headline text variants (typically 60-90 chars) used by responsive formats that render in placements with more available text space.",
      "asset_type": "text",
      "typical_use": "Google Responsive Display Ads / Performance Max / Demand Gen — render alongside short `headlines` when the placement supports a longer headline string. Distinct from `headlines` (short, ≤30 chars typical).",
      "aliases": ["long_headline_pool", "extended_headlines"]
    },
    "descriptions": {
      "description": "Pool of body description text variants.",
      "asset_type": "text",
      "typical_use": "Body-copy variants for surfaces that pick the best combination.",
      "aliases": ["description", "body", "body_text", "text", "content"]
    },
    "images_landscape": {
      "description": "Pool of landscape-orientation images (1.91:1 or 16:9 typical).",
      "asset_type": "image",
      "typical_use": "Hero images for landscape-format placements (Meta feed, LinkedIn feed, Google display).",
      "aliases": ["image", "hero_image", "landscape_image", "banner_image"]
    },
    "images_vertical": {
      "description": "Pool of vertical-orientation images (9:16 typical).",
      "asset_type": "image",
      "typical_use": "Hero images for stories, reels, and other vertical placements (Snap, TikTok, Meta Stories, Pinterest).",
      "aliases": ["vertical_image", "story_image", "portrait_image"]
    },
    "images_square": {
      "description": "Pool of square-orientation images (1:1).",
      "asset_type": "image",
      "typical_use": "Feed-context images, profile-style placements, square carousel cards.",
      "aliases": ["square_image", "feed_image"]
    },
    "logo": {
      "description": "Brand logo asset (typically 1:1 or 2:1).",
      "asset_type": "image",
      "typical_use": "Brand attribution overlay (Google PMax/RDA, Snap Story Ad, Amazon SB).",
      "aliases": ["brand_logo", "logo_image"]
    },
    "video": {
      "description": "Pool of video assets.",
      "asset_type": "video",
      "typical_use": "Video creative for video placements; orientation determined by platform constraints.",
      "aliases": ["video_file", "hero_video", "video_asset", "video_main"]
    },
    "video_vertical": {
      "description": "Pool of vertical-orientation video (9:16).",
      "asset_type": "video",
      "typical_use": "Reels, Stories, TikTok In-Feed, Snap Spotlight, vertical short-form video."
    },
    "video_horizontal": {
      "description": "Pool of horizontal-orientation video (16:9).",
      "asset_type": "video",
      "typical_use": "Pre-roll, mid-roll, instream, CTV, in-feed horizontal video."
    },
    "audio": {
      "description": "Audio asset.",
      "asset_type": "audio",
      "typical_use": "Audio ads for streaming, podcasts, broadcast radio.",
      "aliases": ["audio_file", "hero_audio", "audio_asset", "audio_main"]
    },
    "companion_image": {
      "description": "Image displayed alongside an audio asset.",
      "asset_type": "image",
      "typical_use": "Brand-attribution image paired with audio (Spotify standard 640x640, Amazon DSP audio 300x300)."
    },
    "companion_banner": {
      "description": "Banner image displayed alongside a video asset.",
      "asset_type": "image",
      "typical_use": "Companion banner for instream video (Google video 300x60, Amazon DSP 1.91:1)."
    },
    "brand_name": {
      "description": "Short brand attribution text (distinct from headline).",
      "asset_type": "text",
      "typical_use": "Brand name overlay on Snap, TikTok, Spotify, Pinterest creative."
    },
    "body_text": {
      "description": "Longer free-text body content.",
      "asset_type": "text",
      "typical_use": "Body copy on Reddit, Amazon DSP, LinkedIn formats — distinct from short headlines. IAB OpenRTB Native 1.2 Data Asset type 2."
    },
    "title": {
      "description": "Single headline string rendered verbatim on the creative (no pool / no per-render selection).",
      "asset_type": "text",
      "typical_use": "Native in-feed units, content-recommendation widgets, single-creative display ads where exactly one headline is rendered. IAB OpenRTB Native 1.2 Title Asset (type 1). Distinct from `headlines` (pool of variants for algorithmic surfaces that pick combinations) — `title` is one fixed string the renderer always uses.",
      "aliases": ["headline"]
    },
    "main_image": {
      "description": "Primary image asset rendered as the visual focal point of the creative.",
      "asset_type": "image",
      "typical_use": "Native in-feed units, content-recommendation widgets (the large thumbnail above the headline), single-image display creative. IAB OpenRTB Native 1.2 Image Asset type 3 (Main). Common sizes: 1200×627 (1.91:1), 1080×1080 (1:1), 1080×1350 (4:5).",
      "aliases": ["image_main", "hero_image"]
    },
    "icon": {
      "description": "Small square brand or app icon rendered alongside the main image.",
      "asset_type": "image",
      "typical_use": "App-install native units (app icon), publisher native cards (brand icon), content-recommendation widgets (source publisher icon). IAB OpenRTB Native 1.2 Image Asset type 1 (Icon). Typical size: 80×80 or 100×100, square aspect ratio.",
      "aliases": ["icon_image", "brand_icon"]
    },
    "advertiser_name": {
      "description": "Plain-text name of the advertiser running the creative (rendered with the unit).",
      "asset_type": "text",
      "typical_use": "Native in-feed units, content-recommendation widgets, sponsored-content cards. Maps to the IAB OpenRTB Native 1.2 `sponsoredBy` field — the renderer pairs this with `sponsored_label` (e.g., '<sponsored_label> by <advertiser_name>'). Required on most native surfaces for transparency.",
      "aliases": ["sponsor_name", "brand_name_native"]
    },
    "sponsored_label": {
      "description": "Disclosure label that identifies the unit as sponsored / promoted / advertising content (e.g., \"Sponsored\", \"Promoted\", \"Ad\").",
      "asset_type": "text",
      "typical_use": "Native in-feed units, content-recommendation widgets. The renderer pairs this with `advertiser_name` to surface the IAB-required disclosure. Default value typically \"Sponsored\" or \"Ad\"; sellers may localize.",
      "aliases": ["disclosure_label", "ad_label"]
    },
    "cards": {
      "description": "Per-item carousel card array.",
      "asset_type": "object",
      "typical_use": "Carousel slides on Meta, TikTok, Pinterest, LinkedIn, Reddit. Each card carries its own image/video, headline, and link.",
      "aliases": ["carousel_cards", "slides", "carousel_items", "carousel_slides"]
    },
    "cta": {
      "description": "Call-to-action button label or text.",
      "asset_type": "text",
      "typical_use": "CTA button on display/video/social ad creative (e.g., \"Shop Now\", \"Learn More\"). Most products narrow to a fixed enum via `cta_values`; this canonical entry names the slot itself.",
      "aliases": ["cta_text", "call_to_action", "action_text", "button_text"]
    },
    "price": {
      "description": "Product price slot rendered on the creative — the regular (non-discounted) price.",
      "asset_type": "text",
      "typical_use": "Pinterest shopping pins, Amazon Sponsored Brand product cards, retail-media catalog rendering. IAB OpenRTB Native 1.2 Data Asset type 6. Often pulled from a catalog field via `field_bindings`. Pair with `saleprice` (type 7) to render the discount pattern — by IAB convention `price` is the original (struck-through) and `saleprice` is the discounted amount."
    },
    "display_url": {
      "description": "Visible URL or domain string shown above/below the headline on native units (does not need to match the click destination).",
      "asset_type": "text",
      "typical_use": "Native in-feed and content-recommendation widgets (Taboola, Outbrain, Yahoo Native, AdMob Native). IAB OpenRTB Native 1.2 Data Asset type 11. The actual click destination lives on `landing_page_url`; `display_url` is presentation-only.",
      "aliases": ["visible_url", "displayed_domain"]
    },
    "rating": {
      "description": "Star or score rating rendered on the creative (e.g., \"4.5/5\", \"4.5 stars\").",
      "asset_type": "text",
      "typical_use": "App-install native units, product-rating native cards, review-style content-recommendation. IAB OpenRTB Native 1.2 Data Asset type 3."
    },
    "disclaimer": {
      "description": "Required legal disclaimer or fine print.",
      "asset_type": "text",
      "typical_use": "Pharma, financial services, alcohol, sweepstakes — non-optional in regulated verticals. Receivers may render at reduced size below the primary creative.",
      "aliases": ["legal_text", "fine_print", "legal_disclaimer"]
    },
    "phone_number": {
      "description": "Phone number for click-to-call placements (E.164 preferred).",
      "asset_type": "text",
      "typical_use": "Google call-only ads, Bing call extensions, click-to-call retail/local placements. IAB OpenRTB Native 1.2 Data Asset type 8."
    },
    "likes": {
      "description": "Social-proof like / favorite count rendered on the creative (e.g., \"12.4K likes\").",
      "asset_type": "text",
      "typical_use": "Social-feed native units, app-install native showing aggregate engagement. IAB OpenRTB Native 1.2 Data Asset type 4."
    },
    "downloads": {
      "description": "Download count rendered on the creative (e.g., \"1M+ downloads\").",
      "asset_type": "text",
      "typical_use": "App-install native units (Google Play, App Store ad placements, in-feed app promos). IAB OpenRTB Native 1.2 Data Asset type 5."
    },
    "saleprice": {
      "description": "Sale / discounted price rendered alongside the original `price` slot (e.g., struck-through original + sale price).",
      "asset_type": "text",
      "typical_use": "Retail / e-commerce native showing a discount or promotion. IAB OpenRTB Native 1.2 Data Asset type 7. Pair with `price` (regular price) and optionally `promo_code`.",
      "aliases": ["sale_price", "discount_price"]
    },
    "address": {
      "description": "Physical address rendered on the creative (e.g., for local-business or click-to-visit placements).",
      "asset_type": "text",
      "typical_use": "Local-business native, retail-store ads, click-to-directions placements. IAB OpenRTB Native 1.2 Data Asset type 9."
    },
    "secondary_body_text": {
      "description": "Secondary descriptive copy rendered below the primary `body_text` (extended description).",
      "asset_type": "text",
      "typical_use": "Long-form native units where the renderer accepts a second descriptive paragraph (Yahoo Native long-form, content-recommendation extended cards). IAB OpenRTB Native 1.2 Data Asset type 10 (\"desc2\").",
      "aliases": ["desc2", "body_text_2", "secondary_description"]
    },
    "promo_code": {
      "description": "Promotional / offer code rendered on the creative.",
      "asset_type": "text",
      "typical_use": "Retail / promo creative carrying a coupon code (e.g., \"SAVE20\"). Distinct from offering metadata; this is the rendered text.",
      "aliases": ["offer_code", "coupon_code", "discount_code"]
    },
    "subtitle_file": {
      "description": "Subtitle / closed-caption file for video assets.",
      "asset_type": "url",
      "typical_use": "WebVTT or SRT URL paired with a `video` slot. Required by accessibility-strict products; recommended for most video formats.",
      "aliases": ["caption_file", "captions", "subtitles"]
    },
    "source_catalog": {
      "description": "Catalog asset reference for catalog-driven products.",
      "asset_type": "catalog",
      "typical_use": "Required input on `sponsored_placement` formats. Buyer references a synced catalog by `catalog_id` plus optional item filters."
    },
    "hero_asset": {
      "description": "Optional buyer-supplied hero/banner asset alongside a catalog reference.",
      "asset_type": "image",
      "typical_use": "Pinterest Collection, Snap Collection, Amazon SB Product Collection — buyer supplies a hero image; surface composes catalog tiles below it.",
      "aliases": ["hero_banner", "collection_hero"]
    },
    "landing_page_url": {
      "description": "Click-through destination URL for the ad.",
      "asset_type": "url",
      "typical_use": "Primary destination for ad click-through across all canonical formats.",
      "aliases": [
        "click_url",
        "link",
        "final_url",
        "link_url",
        "click_through_url",
        "landing_url"
      ],
      "note": "Canonical name for the destination URL slot. Six different field names exist across platform format definitions today; adopters should standardize on `landing_page_url` for v2."
    },
    "privacy_policy_url": {
      "description": "Privacy policy URL required for lead-form variants.",
      "asset_type": "url",
      "typical_use": "LinkedIn lead gen, Snap lead gen — required for any format that collects user data."
    },
    "impression_tracker": {
      "description": "Renderer-fired impression tracker URL. Maps to `pixel_tracker` asset on any web-rendered canonical (image, html5, image_carousel, responsive_creative, sponsored_placement, native_*, plus non-VAST events on video_hosted/audio_hosted); maps to `url` asset with `url_type: \"tracker_pixel\"` on VAST/DAAST formats (per the VAST `<Impression>` boundary documented on vast_tracker).",
      "asset_type": "pixel_tracker",
      "typical_use": "Measurement vendor impression pixel that the seller's renderer fires at serve time. For VAST/DAAST formats use the url-asset shape instead.",
      "aliases": ["imp_tracker", "impression_pixel", "imp_url"]
    },
    "click_tracker": {
      "description": "Renderer-fired click tracker URL on native formats. Distinct from `landing_page_url` (the destination); click_tracker is a measurement hop that fires when the user clicks but doesn't navigate the user there.",
      "asset_type": "pixel_tracker",
      "typical_use": "IAB OpenRTB Native `link.clicktrackers[]` — measurement vendor URLs that fire on click in addition to the landing navigation.",
      "aliases": ["click_pixel", "click_measurement_url"]
    },
    "viewability_tracker": {
      "description": "Renderer-fired viewability tracker URL (MRC viewable, video-viewable). One per viewability event the buyer's measurement vendor wants to track.",
      "asset_type": "pixel_tracker",
      "typical_use": "MRC viewable measurement on any web-rendered format; the `pixel_tracker` event field carries the specific viewability variant (viewable_mrc_50, viewable_mrc_100, viewable_video_50, audible_video_complete)."
    },
    "script": {
      "description": "Verbatim text the seller's production reads, dubs, or transforms into the rendered output.",
      "asset_type": "text",
      "typical_use": "Podcast host-read products (host reads buyer's script verbatim), TTS audio synthesis, video voiceover. Distinct from `creative_brief` (looser talking-points style guidance).",
      "aliases": ["script_text", "host_script", "voiceover_script"]
    },
    "creative_brief": {
      "description": "Talking points, brand context, and creative direction for seller-side or generative production.",
      "asset_type": "brief",
      "typical_use": "Generative AI products (text-to-image, text-to-video), brief-driven podcast host-reads (host has discretion within brief), creative-template platforms. Distinct from `script` (verbatim wording) — `creative_brief` gives the producer creative latitude.",
      "aliases": ["brief", "creative_direction", "talking_points"]
    },
    "video_brief": {
      "description": "Structured per-segment generation brief for generative video products.",
      "asset_type": "object",
      "typical_use": "Generative video products (Veo/Sora/Runway-class). Carries `segments[]` where each entry declares order, duration_ms, prompt, optional voiceover and caption. See /schemas/creative/video-brief.json for the typed structure. Distinct from `creative_brief` (free-form text); `video_brief` is the structured timed-prompt form.",
      "aliases": ["scenes", "storyboard", "shot_brief"]
    },
    "voice_id": {
      "description": "Voice selection from a format-defined enum or registered voice catalog.",
      "asset_type": "text",
      "typical_use": "TTS audio synthesis — buyer selects from the platform's voice library. The exact enum is per-format; the canonical name normalizes the slot key."
    },
    "offering_ref": {
      "description": "Reference to a specific offering (product, service, campaign) within the buyer's brand catalog.",
      "asset_type": "text",
      "typical_use": "agent_placement products (focus the AI-surface mention on a specific offering); host-read products (specify which offering is being promoted in the read). Value is an offering_id matched against the buyer's catalog."
    },
    "style_reference": {
      "description": "Reference asset (image) providing per-creative visual style guidance for generative production. Distinct from brand.json — brand.json carries declarative brand-level style (hex colors, voice descriptions, logo asset, tagline) that's stable across campaigns; `style_reference` carries a per-creative reference image (\"make it look like THIS\") that ships in the manifest. For pure brand-style consistency, the manifest's BrandRef resolving brand.json suffices and `style_reference` isn't needed.",
      "asset_type": "image",
      "typical_use": "Image-to-image variation (MidJourney --sref, Adobe Firefly structure/style reference), style transfer, reusing a hero shot's lighting/composition for new creative. Buyer supplies a reference image; seller's generative pipeline produces output matching the visual style.",
      "aliases": ["reference_image", "style_image", "inspiration_image", "structure_reference"]
    },
    "starter_assets": {
      "description": "Pool of reference assets the seller uses as a starting point for transformation or variation.",
      "asset_type": "object",
      "typical_use": "Generative platforms that take an existing creative and produce variations (different sizes, orientations, durations). Buyer supplies the starter; seller derives outputs."
    }
  },
  "governance": {
    "extension_policy": "Non-canonical asset_group_id values remain valid for platform-specific extensions. Validators may emit soft warnings to encourage adoption of canonical values where applicable. New canonical entries are added via PR with rationale, at least one reference adopter, and AAO maintainer review.",
    "alias_policy": "Aliases listed for canonical entries (e.g., `landing_page_url` aliases) are recognized as v1-era variants. v2 adopters should standardize on the canonical name; v1 aliases continue to work for backwards compatibility.",
    "versioning": "This registry is versioned independently of the AdCP spec. Bump `version` on any addition or alias change; preserve existing canonical entries to avoid breaking adopters that have standardized on them."
  }
}