feat: Support location context hint in platform-initiated requests

[jingyli]

Description

Addressing a gap that would extend existing UCP shopping service schema/capabilities to support hyper-local goods (i.e. grocery) use cases:

• Store/Branch Context: Enable platform to provide location hints on top of user addresses, especially if the user has a known "favourite store".

Key Design Decision

Standardized location Field in context.json

• Problem: Cart pricing & availability for these purchase journeys are often tied to specific physical stores, which requires passing a store identifier as hint to businesses (if the location is retrieved through upper-funnel journeys like catalog search).
• Solution: Add an optional location string property directly to context.json. This also allows the hint to be overwritten by more authoritative data constructs like filters.fulfills_to in catalog_search and fulfillment extension's pickup location ID.

Category (Required)

Please select one or more categories that apply to this change.

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

[jamesandersen]

Acknowledging that #589 intends to add a location search capability should this PR be dependent on that one and then specify that values should be from location.json#id? That feels like it would provide both platform and business a clearer expectation about this field (relative to it being an identifier or name hint)

[jingyli]

Good point! I updated the description here to be more explicit that it should be a reference to the location (so it's consistent with the field we have today in catalog filters - https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/shopping/types/fulfillment_destination_filter.json#L18

I don't want to specifically reference back to the json field (i.e. like location.json#id) in the description here since that will imply a required dependency between UCP capabilities. In most cases, that would be the source of which we pull the data from, but if there is another mechanism of which platforms & businesses can communicate this reference back-and-forth then it's also fine to use its value here as-is.

[gsmith85]

I agree with @jingyli that cross-referencing capabilities within schema descriptions introduces potential coupling between capabilities, which we want to avoid.

Still, there is an opportunity to create conceptual connectivity across specifications, which seems to be the crux of @jamesandersen's comment. Instead of cross-referencing capabilities in context.location.description.

I suggest we establish Location as a first-class commerce concept in UCP via the Glossary:

   Term     | Acronym | Definition
  ----------|---------|---------------------------------------------------------------------------------------------------
   Location | -       | A physical entity (e.g., retail store, restaurant, pickup locker, warehouse) identified by a
            |         | stable, business-scoped string (id). Referenced across UCP for buyer localization
            |         | (context.location), store pickup fulfillment, and location discovery.
  ──────

This keeps the JSON Schema decoupled while giving implementers a clear, unified definition of what a location identifier represents across all UCP flows.

[jingyli]

A fair callout, I actually think establishing this as a UCP concept should belong to #589 instead of this PR here (as that is where the overarching capability will be introduced). PTAL at 5e3ff05!