{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.1.0-rc.4/core/offering.json",
  "title": "Offering",
  "description": "A promotable offering from a brand. Can represent a campaign, product promotion, service, or any other thing the brand wants to make available. Offerings carry structured asset groups for creative assembly and can be promoted via traditional creatives or conversational SI experiences (via the brand's SI agent).",
  "type": "object",
  "properties": {
    "offering_id": {
      "type": "string",
      "description": "Unique identifier for this offering. Used by hosts to reference specific offerings in si_get_offering calls.",
      "x-entity": "offering"
    },
    "name": {
      "type": "string",
      "description": "Human-readable offering name (e.g., 'Winter Sale', 'Free Trial', 'Enterprise Platform')"
    },
    "description": {
      "type": "string",
      "description": "Description of what's being offered"
    },
    "tagline": {
      "type": "string",
      "description": "Short promotional tagline for the offering"
    },
    "valid_from": {
      "type": "string",
      "format": "date-time",
      "description": "When the offering becomes available. If not specified, offering is immediately available."
    },
    "valid_to": {
      "type": "string",
      "format": "date-time",
      "description": "When the offering expires. If not specified, offering has no expiration."
    },
    "checkout_url": {
      "type": "string",
      "format": "uri",
      "description": "URL for checkout/purchase flow when the brand doesn't support agentic checkout."
    },
    "landing_url": {
      "type": "string",
      "format": "uri",
      "description": "Landing page URL for this offering. For catalog-driven creatives, this is the per-item click-through destination that platforms map to the ad's link-out URL. Every offering in a catalog should have a landing_url unless the format provides its own destination logic."
    },
    "assets": {
      "type": "array",
      "description": "Structured asset groups for this offering. Each group carries a typed pool of creative assets (headlines, images, videos, etc.) identified by a group ID that matches format-level vocabulary.",
      "items": {
        "$ref": "/schemas/3.1.0-rc.4/core/offering-asset-group.json"
      }
    },
    "geo_targets": {
      "type": "object",
      "description": "Geographic scope of this offering. Declares where the offering is relevant — for location-specific offerings such as job vacancies, in-store promotions, or local events. Platforms use this to target geographically appropriate audiences and to filter out offerings irrelevant to a user's location. Uses the same geographic structures as targeting_overlay in create_media_buy.",
      "properties": {
        "countries": {
          "type": "array",
          "description": "Countries where this offering is relevant. ISO 3166-1 alpha-2 codes (e.g., 'US', 'NL', 'DE').",
          "items": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "minItems": 1
        },
        "regions": {
          "type": "array",
          "description": "Regions or states where this offering is relevant. ISO 3166-2 subdivision codes (e.g., 'NL-NH', 'US-CA').",
          "items": {
            "type": "string",
            "pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
          },
          "minItems": 1
        },
        "metros": {
          "type": "array",
          "description": "Metro areas where this offering is relevant. Each entry specifies the classification system and target values.",
          "items": {
            "type": "object",
            "properties": {
              "system": {
                "$ref": "/schemas/3.1.0-rc.4/enums/metro-system.json",
                "description": "Metro area classification system (e.g., 'nielsen_dma', 'uk_itl2')"
              },
              "values": {
                "type": "array",
                "description": "Metro codes within the system",
                "items": {
                  "type": "string"
                },
                "minItems": 1
              }
            },
            "required": ["system", "values"],
            "additionalProperties": true
          },
          "minItems": 1
        },
        "postal_areas": {
          "type": "array",
          "description": "Postal areas where this offering is relevant. Each entry specifies the postal system and target values.",
          "items": {
            "type": "object",
            "properties": {
              "system": {
                "$ref": "/schemas/3.1.0-rc.4/enums/postal-system.json",
                "description": "Postal code system (e.g., 'us_zip', 'de_plz')"
              },
              "values": {
                "type": "array",
                "description": "Postal codes within the system",
                "items": {
                  "type": "string"
                },
                "minItems": 1
              }
            },
            "required": ["system", "values"],
            "additionalProperties": true
          },
          "minItems": 1
        }
      },
      "additionalProperties": true
    },
    "keywords": {
      "type": "array",
      "description": "Keywords for matching this offering to user intent. Hosts use these for retrieval/relevance scoring.",
      "items": {
        "type": "string"
      }
    },
    "categories": {
      "type": "array",
      "description": "Categories this offering belongs to (e.g., 'measurement', 'identity', 'programmatic')",
      "items": {
        "type": "string"
      }
    },
    "ext": {
      "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
    }
  },
  "required": ["offering_id", "name"],
  "additionalProperties": true,
  "examples": [
    {
      "description": "Time-limited promotional offer with checkout",
      "data": {
        "offering_id": "q1-2025-trial",
        "name": "Free 30-day trial",
        "description": "Try our carbon measurement platform free for 30 days",
        "tagline": "Start measuring your digital carbon footprint today",
        "valid_from": "2025-01-01T00:00:00Z",
        "valid_to": "2025-03-31T23:59:59Z",
        "checkout_url": "https://vendor.example.com/signup",
        "keywords": ["carbon", "sustainability", "measurement", "emissions"],
        "categories": ["measurement", "sustainability"]
      }
    },
    {
      "description": "Product offering with landing page",
      "data": {
        "offering_id": "enterprise-dsp",
        "name": "Enterprise DSP Platform",
        "description": "Full-featured demand-side platform for enterprise advertisers",
        "landing_url": "https://thetradedesk.com/enterprise",
        "keywords": ["dsp", "programmatic", "rtb", "ctv"],
        "categories": ["programmatic", "dsp"]
      }
    },
    {
      "description": "Location-specific offering with geo targets",
      "data": {
        "offering_id": "vacancy-amsterdam-chef-42",
        "name": "Head Chef — Amsterdam",
        "description": "Full-time head chef position at our Amsterdam location",
        "landing_url": "https://careers.acme.com/vacancies/42",
        "geo_targets": {
          "countries": ["NL"],
          "regions": ["NL-NH"]
        }
      }
    },
    {
      "description": "Offering with structured asset groups",
      "data": {
        "offering_id": "summer-sale",
        "name": "Summer Sale",
        "description": "Up to 50% off summer collection",
        "landing_url": "https://acme.com/summer",
        "assets": [
          {
            "asset_group_id": "headlines",
            "asset_type": "text",
            "items": [
              {"asset_type": "text", "content": "Shop the Summer Sale"},
              {"asset_type": "text", "content": "50% Off Everything"},
              {"asset_type": "text", "content": "Summer Savings Event"}
            ]
          },
          {
            "asset_group_id": "images_landscape",
            "asset_type": "image",
            "items": [
              {"asset_type": "image", "url": "https://cdn.acme.com/hero.jpg", "width": 1200, "height": 628}
            ]
          },
          {
            "asset_group_id": "images_square",
            "asset_type": "image",
            "items": [
              {"asset_type": "image", "url": "https://cdn.acme.com/sq.jpg", "width": 600, "height": 600}
            ]
          }
        ]
      }
    }
  ]
}