feat: Support location context hint in platform-initiated requests - #642
Merged
jingyli merged 11 commits intoAug 13, 2026
Merged
Conversation
gsmith85
reviewed
Jul 29, 2026
Establish Location as a stable, opaque, Business-scoped commerce concept and align context.location with that identity. Keep the field as a provisional string hint whose effects are defined by the active operation, capability, or extension, without coupling it to Location discovery.
igrigorik
approved these changes
Aug 12, 2026
igrigorik
left a comment
igrigorik
left a comment
Contributor
There was a problem hiding this comment.
@jingyli @gsmith85 @jamesandersen pushed a small update (0b5035e) to hopefully bring this one home. Taking Greg's suggestion on Glossary, ptal.
Contributor
Author
|
Thanks @igrigorik for 0b5035e - update LG though one nit I'd like to update on top of is to remove the explicit |
…s defined by the enclosing capability.
gsmith85
reviewed
Aug 12, 2026
| "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 or extension defines its effects." |
Contributor
There was a problem hiding this comment.
The operation specification or an active capability or extension defines its effects.
Minor nit: Replace the first "or" with a comma
Contributor
There was a problem hiding this comment.
No I think 'or' is correct. It's saying operation (e.g. create_cart) or extension (e.g. org.foo.fancy-fulfillment that extends dev.ucp.cart) define the semantics of this field.
Contributor
There was a problem hiding this comment.
@jingyli - can we add the examples back in the schema file to make it clearer?
Contributor
Author
There was a problem hiding this comment.
@gsmith85 To @igrigorik's callout above, I think the first or should still be preserved. However, the second one (an active capability or extension) can be simplified to just a / so the sentence runs a bit more smoothly. Made the corresponding update, PTAL!
@amithanda Added back the common example for retail shopping, PTAL!
Contributor
|
@jingyli @gsmith85 lgtm on updated shape. @amithanda final pass? |
amithanda
approved these changes
Aug 12, 2026
amithanda
left a comment
amithanda
left a comment
Contributor
There was a problem hiding this comment.
Added a minor suggestion, PTAL.
…e for retail shopping.
gsmith85
approved these changes
Aug 13, 2026
igrigorik
added a commit
that referenced
this pull request
Aug 13, 2026
Base Context (#642) carries an optional `context.location`, a stable opaque identifier for a Business Location, and defers its effects to the operation specification or an active capability/extension. Nothing had taken up that deferral, so a Platform sending a store ID had no advertised behavior to rely on, and Catalog's existing `filters.fulfills_to` looked like a competing way to say the same thing. Fulfillment now defines those effects. When the Fulfillment extension is active, `context.location` names the provisional Business Location that a Business evaluates fulfillment availability against and generates initial fulfillment choices for; it never selects a destination. Precedence is scoped to what each field governs: `filters.fulfills_to` supersedes the Context locality fields and `context.location` for fulfillment destination and availability resolution only, and once a Platform sets `selected_destination_id` that selection governs its own method. Base Cart Context already carries `location`, and cart-to-checkout conversion initializes Checkout from the Cart's context, so a Catalog -> Cart -> Checkout journey preserves the identifier and an explicit Checkout selection then governs it. The schema delta is description-only, correcting four field descriptions that were inaccurate or circular: the root named only Checkout as a parent though Fulfillment also extends Catalog; `methods[].location` defined itself as "a location id" rather than as the Location the glossary now names; method `options` claimed the high-resolution set is negotiated in Cart; and `fulfills_to` claimed it supersedes `context` wholesale, which would imply overriding unrelated fields such as `context.currency`.
igrigorik
added a commit
that referenced
this pull request
Aug 17, 2026
* add negotiated fulfillment location context Store-scoped Catalog results had no advertised way to preserve the Business location through Cart and into Checkout. Defining the field on base Context would make every Shopping implementation accept an opaque Business-scoped identifier without advertising the behavior that produces or consumes it. Have Fulfillment contribute `context.location` to Catalog requests, Cart, and Checkout through explicit parent composition. Cart receives only the location context, and implementations supporting both Catalog and Cart should extend both to preserve continuity. For example, `loc_123` can scope Catalog availability, continue through Cart, and become explicit only when selected as a Checkout destination. Introduce a shared Location Identifier and reuse it for Fulfillment context, Catalog method locations, destination filters, and retail locations. This preserves one identity across surfaces while each containing field defines its role. Keep `selected_destination_id` generic because it may also reference non-location destinations. * feat: define Fulfillment behavior for location context Base Context (#642) carries an optional `context.location`, a stable opaque identifier for a Business Location, and defers its effects to the operation specification or an active capability/extension. Nothing had taken up that deferral, so a Platform sending a store ID had no advertised behavior to rely on, and Catalog's existing `filters.fulfills_to` looked like a competing way to say the same thing. Fulfillment now defines those effects. When the Fulfillment extension is active, `context.location` names the provisional Business Location that a Business evaluates fulfillment availability against and generates initial fulfillment choices for; it never selects a destination. Precedence is scoped to what each field governs: `filters.fulfills_to` supersedes the Context locality fields and `context.location` for fulfillment destination and availability resolution only, and once a Platform sets `selected_destination_id` that selection governs its own method. Base Cart Context already carries `location`, and cart-to-checkout conversion initializes Checkout from the Cart's context, so a Catalog -> Cart -> Checkout journey preserves the identifier and an explicit Checkout selection then governs it. The schema delta is description-only, correcting four field descriptions that were inaccurate or circular: the root named only Checkout as a parent though Fulfillment also extends Catalog; `methods[].location` defined itself as "a location id" rather than as the Location the glossary now names; method `options` claimed the high-resolution set is negotiated in Cart; and `fulfills_to` claimed it supersedes `context` wholesale, which would imply overriding unrelated fields such as `context.currency`. * clarify fulfills_to wording `fulfills_to` now describes where "items" are fulfilled rather than "the order": no order exists during Catalog search, and "items" also reads correctly at Checkout. The gift example says why a destination diverges from `context`. Supersession is stated generically: `fulfills_to` supersedes `context` only for fulfillment destination and availability resolution. The scope clause carries the bound, so enumerating the locality fields and `context.location` was redundant and would rot as Context grows. Prose keeps the boundary explicit with "Other `context` fields are unaffected." The destination shape is no longer restated here or in prose. It belongs to `fulfillment_destination_filter.json` and `locality.json`, which this field composes, and `allOf` descriptions coexist rather than override, so the contract was published twice. The bullet links to the rendered filter section instead.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Addressing a gap that would extend existing UCP shopping service schema/capabilities to support hyper-local goods (i.e. grocery) use cases:
Key Design Decision
Standardized
locationField incontext.jsonlocationstring property directly tocontext.json. This also allows the hint to be overwritten by more authoritative data constructs likefilters.fulfills_toincatalog_searchandfulfillmentextension's pickup location ID.Category (Required)
Please select one or more categories that apply to this change.
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Checklist
!for breaking changes).Screenshots / Logs (if applicable)