{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/2026-08-25/schemas/common/types/context.json",
  "title": "Context",
  "description": "Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.",
  "type": "object",
  "additionalProperties": true,
  "allOf": [
    {
      "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/locality.json"
    },
    {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "location": {
          "type": "string",
          "description": "Stable, opaque identifier for a Location in the Business's namespace. This provisional, non-binding hint is distinct from the Buyer's locality. The operation specification or an active capability/extension defines its effects. A common example in retail shopping is the default home store ID selected and saved by the user when purchasing groceries."
        },
        "intent": {
          "type": "string",
          "description": "Background context describing buyer's intent (e.g., 'looking for a gift under $50', 'need something durable for outdoor use'). Informs relevance, recommendations, and personalization."
        },
        "language": {
          "type": "string",
          "description": "Preferred language for content. Use IETF BCP 47 language tags (e.g., 'en', 'fr-CA', 'zh-Hans'). For REST, equivalent to Accept-Language header—platforms SHOULD fall back to Accept-Language when this field is absent; when provided, overrides Accept-Language. Businesses MAY return content in a different language if unavailable."
        },
        "currency": {
          "type": "string",
          "description": "Preferred currency (ISO 4217, e.g., 'EUR', 'USD'). Businesses determine presentment currency from context and authoritative signals; this hint MAY inform selection in multi-currency markets. Also serves as the denomination for price filter values — platforms SHOULD include this field when sending price filters. Response prices include explicit currency confirming the resolution."
        },
        "eligibility": {
          "type": "array",
          "description": "Buyer claims about eligible benefits such as loyalty membership, payment instrument perks, and similar. Recognized claims MAY inform the Business response (e.g., member-only product availability, adjusted pricing in catalog, provisional discounts at cart or checkout). Businesses MUST ignore unrecognized values without error. Values MUST use reverse-domain naming (e.g., 'com.example.loyalty_gold', 'org.school.student') and MUST be non-identifying.",
          "uniqueItems": true,
          "items": {
            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
          }
        },
        "payment": {
          "type": "array",
          "description": "Buyer-preferred payment handlers in priority order (most preferred first). Each entry names a handler advertised in the Business profile's `ucp.payment_handlers`, optionally narrowed to preferred instrument types. The Business SHOULD use it to preselect or prioritize the handler (and type, when given) and MAY ignore unavailable or ineligible entries; unrecognized values MUST be ignored without error.",
          "items": {
            "type": "object",
            "required": [
              "handler"
            ],
            "properties": {
              "handler": {
                "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json",
                "description": "Handler registry key advertised in the Business profile's `ucp.payment_handlers`."
              },
              "types": {
                "type": "array",
                "description": "Optional preferred instrument types for this handler, in priority order, aligned with the handler's advertised `payment_instrument.type` values (for example `card` or `bank`). Unrecognized values MUST be ignored.",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  ]
}