feat!: Introduce Location Search + Lookup capabilities - #589
Conversation
…ing/ to generally represent any physical location (to be referenced by Location capability).
jingyli
added
TC review
There was a problem hiding this comment.
Overall, the shape and proposal make sense—ty for scaffolding this. A few design questions I'd like to work through...
1. Should common be the service, or the namespace containing a Location service?
The capability names are scoped to Location:
dev.ucp.common.location.search
dev.ucp.common.location.lookup
The profile examples, however, advertise the transport as:
{
"services": {
"dev.ucp.common": [{ "...": "..." }]
}
}I agree with dev.ucp.common.* as the namespace for cross-vertical primitives. However, I'm not sure about making dev.ucp.common one catch-all service: every future shared capability would then share an endpoint, transport schema, etc.
The alternative split is:
namespace: dev.ucp.common.*
service: dev.ucp.common.location
capabilities: dev.ucp.common.location.search
dev.ucp.common.location.lookup
Do we think a catch-all .common service is preferred to scoped services?
2. Is geofence_radius sufficient to model the domain?
The current geo object combines a physical point with a circular geofence_radius, while geofence_point asks whether a requested point falls inside that circle. This covers a useful simple case, but in my experience service areas are often irregular polygons, disjoint regions, postal-code unions, etc.
Do we need to model (thin, hopefully) RFC 7946-based service-area shape supporting Polygon / MultiPolygon?
3. Can we adopt a Schema.org-inspired shape instead of inventing a bespoke one?
The latest changes make the custom model deterministic by defining 24:00, precedence between is_closed / is_24_hours / intervals, and a two-entry convention for overnight hours. That is an improvement, but it also highlights how much new protocol syntax and interpretation logic we are defining.
Schema.org's OpeningHoursSpecification already provides the core semantics we need:
dayOfWeek,opens, andcloses;- multiple entries for split shifts;
closes < opensmeans the interval spans the next day;- no
opensmeans closed; validFrom/validThroughcover date-specific exceptions.
A Schema.org-inspired UCP shape could look like:
{
"timezone": "America/New_York",
"hours": [
{ "day_of_week": "monday", "opens": "09:00", "closes": "17:00" },
{ "day_of_week": "monday", "opens": "18:00", "closes": "22:00" },
{ "day_of_week": "friday", "opens": "22:00", "closes": "02:00" }
],
"exception_hours": [
{
"valid_from": "2026-12-24",
"valid_through": "2026-12-24",
"opens": "09:00",
"closes": "14:00"
},
{
"valid_from": "2026-12-25",
"valid_through": "2026-12-25"
}
]
}The contract is compact: each entry describes one open interval; repeated entries for the same day represent split shifts; a closes value earlier than opens spans midnight; and a date-bounded exception without opens means closed for that period. timezone supplies the interpretation context for local times. The example adapts Schema.org's semantics to UCP's snake_case naming and HH:MM convention rather than copying its JSON-LD representation verbatim.
Is there a concrete requirement that OpeningHoursSpecification cannot model? If not, I would align to it and remove the custom closed/24-hour flags, precedence rules, and overnight splitting convention.
4. Is offerings.inventory.quantity an inventory-disclosure query?
The store-finder use case—"which nearby location can fulfill the item I need?"—is valuable. A hard minimum quantity filter, however, lets a caller repeatedly probe thresholds and approximate a store's stock level even when the response never returns a count.
I suggest framing this as Buyer demand and coarse availability, not inventory disclosure:
- reuse UCP's existing availability semantics rather than parallel inventory concept;
- treat requested quantity as intent that a Business may coarsen;
- change language to not imply that exact on-hand counts are returned;
5. What does offerings mean? 😅
Modelled request can filter on:
{
"offerings": {
"amenities": ["..."],
"inventory": [{ "id": "..." }]
}
}The standardized Location entity, however, exposes neither amenities nor offerings. Although the filter contract implies that each returned Location satisfies the requested values, a Platform cannot render the matched facts, inspect additional amenities, or present structured item availability from the response without relying on vendor-defined fields. There is also a category question: amenities are relatively static Location characteristics, while item availability is dynamic and tied to another Catalog or menu identity. Grouping both under offerings may be convenient structurally, but does not necessarily make them one semantic concept.
My inclination would be to put static amenities on Location, model dynamic availability separately using the existing UCP availability vocabulary, and flatten the filter unless offerings gains a clearer cross-vertical contract.
6. What amenity vocabulary is interoperable across Businesses and verticals?
An open string is the right wire type for UCP, but the current proposal defines no well-known values. Should UCP publish a small open vocabulary for interoperable matching, and which initial values are important enough to standardize?
7. What are the capability-specific security and privacy requirements?
Location handles Buyer location hints, enumerates physical sites, describes service coverage, and can be used to probe per-location item availability. The generic Signals reference and current privacy note do not cover those capability-specific risks.
I think the specification needs explicit Security and Privacy Considerations covering:
- coarse-by-default Buyer location and progressive disclosure;
- purpose limitation and retention of location inputs;
- store/site enumeration and rate limiting;
- inventory and availability probing;
- disclosure of internal, private, or non-buyer-visible locations;
- disclosure of precise service-area geometry.
8. What is the bounded Location projection for Catalog and Checkout?
This PR points Checkout’s pickup destination directly at the rich common Location entity. That couples Checkout to the complete Location discovery model: geo, hours, service area, amenities, and every future Location extension would automatically accrete into the transactional response. I don't think that's right.
In Catalog Fulfillment (#507), we deliberately introduced a thin Location projection: a stable location ID plus method description. This avoided embedding an N-store matrix in product results and deferred richer Location facts to a separately negotiated capability. That boundary still makes sense, but I think there is a middle ground: split Location into a bounded base and an extended discovery entity.
Base Location
id
name
address?
│
└── allOf → Extended Location
geo
hours
exception_hours
timezone
amenities
service_area
Catalog and Checkout would use the bounded, buyer-renderable base. Location Search/Lookup would return the extended entity when the service is negotiated. Platform requests would select a Location by stable id rather than asserting Business-owned name/address facts. This preserves the bounded Catalog model from #507, keeps Catalog and Checkout independently renderable, and prevents the full Location discovery model from accreting into every Checkout response.
Location search intentionally permits Business-defined filters, but the schema relied on JSON Schema's implicit open-object default while the prose named additionalProperties as the extension mechanism. Declare the extension point explicitly so schema readers and generated documentation can distinguish intentional extensibility from omission. Strict resolution remains a caller-selected closed-world override.
Location documentation inherited Catalog-specific descriptions, rendering contexts, and a severity policy that Location never defined. It also documented a singular REST path and a filter name that do not exist in the binding/schema. Use Location-specific llms.txt descriptions and render scopes, remove the unsupported severity claim, and align the visible endpoint and filter names with their canonical definitions.
|
+1 on scoping the service to The setup. Suppose "services": {
"dev.ucp.common": [{
"version": "2026-04-08",
"transport": "rest",
"schema": ".../services/common/rest.openapi.json",
"endpoint": "https://business.example.com/ucp"
}]
}One endpoint, one transport document, and one version covering store lookup, review retrieval, and identity linking. That seems to make three fairly ordinary deployments unexpressible:
The scoped form expresses all three directly, including the case where two domains happen to share a host: "services": {
"dev.ucp.common.location": [{
"version": "2026-04-08", "transport": "rest",
"schema": ".../services/common/location/rest.openapi.json",
"endpoint": "https://stores.business.example.com/ucp"
}],
"dev.ucp.common.reviews": [{
"version": "2026-01-11", "transport": "rest",
"schema": ".../services/common/reviews/rest.openapi.json",
"endpoint": "https://ucp.reviews-vendor.example.com/business-123"
}],
"dev.ucp.common.identity": [{
"version": "2026-04-08", "transport": "rest",
"schema": ".../services/common/identity/rest.openapi.json",
"endpoint": "https://business.example.com/ucp"
}]
}The asymmetry I think settles it: scoped services can emulate the catch-all, but the catch-all cannot emulate scoped. A business serving everything from one gateway just points every scoped entry at the same Would it be worth writing the rule down explicitly, something like: a service is the unit of deployment, not the unit of naming? A new service is warranted whenever a domain could plausibly be operated by a different party, on different infrastructure, or on a different release cadence than its siblings. I like that framing because it explains the existing corpus rather than contradicting it. |
For suggestion 2. above could we just drop the circle instead of upgrading it to polygons?
That matters because publishing it as a circle is currently self-contradictory. Proposal: drop
Why this looks better than adding |
| "components": { | ||
| "parameters": { | ||
| "authorization": { | ||
| "name": "Authorization", |
There was a problem hiding this comment.
Authorization cannot be modeled as an ordinary header parameter in OpenAPI 3.1; compliant tooling is required to ignore a header parameter with that name. Because this document also has no securitySchemes or root/operation security requirements, generated clients and gateways will interpret these operations as unauthenticated. UCP-Agent identifies a claimed profile but does not prove who sent the request. Please model the supported authentication alternatives through securitySchemes and operation-level security, explicitly represent anonymous public search if that is supported, and state that authentication and authorization occur before location-ID resolution or filtering.
There was a problem hiding this comment.
That's a great find and I think one that is also affecting our existing openapi services - e.g., https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/services/shopping/rest.openapi.json#L808! To keep the scope of the PR focused on the new capability, I'm going to keep this as-is here but have filed #668 to track a quick follow-up fix that would universally apply to all openapi service definitions we have.
| } | ||
| }, | ||
| "responses": { | ||
| "200": { |
There was a problem hiding this comment.
Both operations currently document only a 200 response even though the specification defines invalid-request, authentication, rate-limit, and server-error behavior. Autonomous clients need machine-readable distinctions between terminal errors, caller-correctable errors, and retryable failures; otherwise they may retry unauthorized requests, silently abandon valid searches, or amplify an outage. Please add the shared UCP error envelope for at least 400, 401, 403, 429, and 5xx, require Retry-After where appropriate, and align the REST and MCP behavior for an oversized lookup batch. The current documentation alternates between implementation-defined limits and a 400; please choose one normative status and error code.
There was a problem hiding this comment.
Another great callout as I also recall seeing feedback from the community - #131 (section in Standardize Error Responses on explicitly mapping out protocol-level errors.
I'd like to keep this PR focused on the capability design and propose a follow-up to enhance all openapi definitions (e.g., https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/services/shopping/rest.openapi.json).
| "format": "uuid", | ||
| "description": "Unique key for retry safety. Maps to HTTP Idempotency-Key header (optional for read-only operations)." | ||
| }, | ||
| "signature": { |
There was a problem hiding this comment.
This introduces a detached JWS in the MCP JSON metadata, while UCP specifies RFC 9421 HTTP Message Signatures for HTTP transports, including MCP Streamable HTTP. These mechanisms are not wire-compatible and the new field leaves canonicalization, covered fields, key resolution, and replay parameters underspecified. Please remove the JSON-level detached JWS and use Signature-Input, Signature, and Content-Digest at the HTTP transport layer, consistent with the other UCP services. If a non-HTTP MCP transport is introduced later, its signing model should be specified independently rather than overloading this metadata field.
There was a problem hiding this comment.
17dac60 corrected the terminology but not the protocol layer: signature, signature_input, and content-digest remain JSON members of meta. RFC 9421 defines Signature and Signature-Input as HTTP fields, and UCP's existing MCP signing guidance places those fields plus Content-Digest in HTTP headers and explicitly avoids a duplicate JSON representation. Implementations following this OpenRPC document would sign a different wire contract than implementations following the core signing specification.
jingyli
changed the title
…e more flexible combination of request inputs.
…how business should handle contextual hints fallback.
|
Thanks @maximenajim for the feedback! Responses added and requesting for another passthrough. |
| }, | ||
| { | ||
| "$ref": "retail_location.json" | ||
| "$ref": "../../common/types/location_base.json", |
There was a problem hiding this comment.
Every location_base instance has id and name, while shipping_destination requires only id and permits unknown properties through its composed postal-address schema. A normal BOPIS destination such as {"id":"store-1","name":"Downtown","address":{"postal_code":"55403"}} therefore matches both branches and is rejected by oneOf; the current schema makes the bounded pickup projection unusable in Checkout.
Please select the destination schema from the containing fulfillment method—for example, type: "shipping" constrains destinations.items to shipping_destination and type: "pickup" constrains them to location_base—or add an explicit discriminator that makes the branches mutually exclusive. Add a conformance case with id, name, and address.
| }, | ||
| "ucp_request": "omit" | ||
| }, | ||
| "hours": { |
There was a problem hiding this comment.
The revised interval behavior is inspired by schema.org, but the wire representation still replaces its deployed vocabulary with hours, exception_hours, day, open, close, from, and through. Existing merchant JSON-LD uses openingHoursSpecification, specialOpeningHoursSpecification, dayOfWeek, opens, closes, validFrom, and validThrough; schema.org-aware generators and validators will not recognize the proposed fields, and through also uses a different exclusive-date convention.
|
I completed another pass. The proposal is looking good. I added a few more follow-up comments. |
igrigorik
left a comment
igrigorik
left a comment
There was a problem hiding this comment.
Thanks Jing — we're headed in the right direction. Lots of good feedback already, I'll focus on a couple of big questions/flags I'd like us to align and iterate on...
Let's reuse the existing Catalog and Shopping contracts
Location should inherit the established search and identifier-resolution semantics wherever they apply. Unqualified serves(target) should mean that any currently available method can serve the target. inventory[].id should remain opaque and Business-resolved, while its status predicate reuses Shopping's availability vocabulary. We should explicitly define omitted and conflicting inventory-status predicates. One forward-compatibility caveat: serves is currently closed and probably shouldn't be; adding a method qualifier later would require a schema/version change unless we preserve that extension point now.
Q: should amenities be a reverse-domain-name keyed map?
We currently model each amenity as a string, which is simple if the contract is only “this Location has this amenity.” Did we consider—or do we want—to model amenities as a reverse-domain-name keyed map instead?
I'd like to stress-test whether we'll eventually want properties attached to an amenity, such as a subtype, restrictions, availability, or other metadata. If amenities are deliberately Boolean membership identifiers, the current string array is fine. If we expect them to become extensible assertions, an RNDS map would give us namespace ownership and room for additional properties without a later array-to-map wire break.
Remaining hours schema and semantic issues together
The latest updates fixed timezone enforcement and some earlier exception-hour inconsistencies, but the current contract still has unresolved issues:
open_nowandopen_atmay both be supplied, with implementation-defined precedence or OR behavior;exception_hoursuses00:00–00:00for full-day closure, leaving no unambiguous 24-hour-open representation and no defined equal-time behavior for regular hours;- exclusive
throughdiffers from Schema.org's inclusivevalidThroughwithout an explicit conversion rule; - regular versus exception precedence, overlapping exceptions, split and overnight intervals, and closure behavior are not defined as one evaluation model;
- the renamed UCP fields do not yet have a mechanical mapping to the corresponding Schema.org vocabulary.
Building on Maxime's existing thread, I think these should be resolved as one atomic schema, prose, and examples change rather than adjusting the pieces independently—potentially as a standalone stacked PR.
Separate the existing Fulfillment destination debt from the Location capability
This is a big one, because it points to existing spec debt. Maxime's oneOf comment exposes an existing Fulfillment problem: the shipping and Business Location destination branches overlap, the request projection does not reduce Location selection to a stable ID reference, and the surrounding contract does not guarantee that a discovered Location is accepted by the applicable Fulfillment method.
Replacing retail_location.json with location_base.json does not by itself solve those issues, and it also changes an existing published path. I recommend handling this as a separately reviewed breaking Fulfillment refactor—discriminator, bounded response projection, ID-based request selection, identity guarantee, and compatibility plan—that #589 can then build on.
Destination authorship is a function of the enclosing method's type:
shipping destinations are Platform-authored; pickup destinations are
Business-authored (the Platform selects one, never writes one); and
extension-defined method types specify their own destination shape and
writability.
- Destination `type` is required in responses, optional in requests.
When a request destination omits it, the method's type implies the
shape: untyped destinations under `shipping` validate as Shipping
Destinations via new method-level conditioning (the conditioning of
destinations[] on method.type the original schema lacked). A Platform
MAY include `type` to disambiguate a reference when more than one
kind can appear under a method (e.g. an id-only destination
referencing a Business-managed mailing address vs an identity
provider's customer address book).
- Removed the writable business-location destination (`{type, id}`
request stub). `selected_destination_id` is the sole
location-selection channel; it accepts any stable, Business-scoped
Location ID the Business recognizes for the method, including IDs not
yet enumerated in destinations[] (the #589 handoff). The Business
returns the typed Location Summary in its response.
- Updated prose, field docs, and request-direction examples accordingly.
Validated: ucp-schema lint, validate_examples (296 pass),
test_validate_examples (50 pass), strict spec build, check_links.
…ly in requests A fulfillment method's type selects the shape of its entire subtree, destinations included: a shipping method has shipping-address destinations, a pickup method has business-location destinations, and extension-defined method types define their own. Polymorphism is resolved at the parent, so request destinations need no per-object discriminator. - fulfillment_method branches per method type; the generic fulfillment_destination union is no longer referenced by schemas (kept for response documentation). - Destination type is required in responses, optional in requests. - destinations under pickup is response-only (ucp_request omit inside the pickup branch): under strict resolution the Platform cannot write business locations. selected_destination_id is the sole selection channel and accepts any Business-scoped Location ID the Business recognizes for the method, including IDs not yet enumerated (#589 handoff). - dependentRequired: a request that writes destinations[] must carry the method's type. - Removed explicit additionalProperties:true from fulfillment_method (behavior-neutral in open validation; lets strict sealing work). - Existing request wire shapes are unchanged; responses gain the required type field. Assisted-By: devx/296664b9-53b6-409a-989a-ace9d3348247
* fix!: discriminate destinations at the method level; type response-only in requests A fulfillment method's type selects the shape of its entire subtree, destinations included: a shipping method has shipping-address destinations, a pickup method has business-location destinations, and extension-defined method types define their own. Polymorphism is resolved at the parent, so request destinations need no per-object discriminator. - fulfillment_method branches per method type; the generic fulfillment_destination union is no longer referenced by schemas (kept for response documentation). - Destination type is required in responses, optional in requests. - destinations under pickup is response-only (ucp_request omit inside the pickup branch): under strict resolution the Platform cannot write business locations. selected_destination_id is the sole selection channel and accepts any Business-scoped Location ID the Business recognizes for the method, including IDs not yet enumerated (#589 handoff). - dependentRequired: a request that writes destinations[] must carry the method's type. - Removed explicit additionalProperties:true from fulfillment_method (behavior-neutral in open validation; lets strict sealing work). - Existing request wire shapes are unchanged; responses gain the required type field. Assisted-By: devx/296664b9-53b6-409a-989a-ace9d3348247 * clarify directional destination typing Fulfillment responses always self-describe with a required destination type, while Platform requests follow the enclosing method's authorship contract. Clarify that untyped destinations under the well-known shipping method default to Shipping Destination, pickup destinations are Business-authored and selected through selected_destination_id, and other method types define their own request shape and Platform writability. Remove the unsupported suggestion that an alternate destination type can be selected under core shipping. An ID-only saved or provider-held address remains a Shipping Destination; provider provenance or additional fields require a negotiated extension contract. --------- Co-authored-by: Ilya Grigorik <ilya@grigorik.com>
6 participants
Description
A mirror copy of #545 that supersedes it.
Defines standard interfaces for discovering, searching, and retrieving physical locations (e.g., retail stores, restaurants, warehouses, lodging properties).
It introduces two new capabilities under the
dev.ucp.commonnamespace (consistent with Shopping's Catalog capability design):dev.ucp.common.location.search): Discovery-focused endpoint for natural language query, geographic, and offerings-based filters.dev.ucp.common.location.lookup): Resolution-focused endpoints supporting single & batch lookups.Some key commerce flows it will be able to unlock:
nearby that support customer pickup and checking their operating hours & inventory availability
before selection.
or local service provider) has delivery coverage for a buyer's address.
Category (Required)
ucp-schematool (resolver, linter, validator). (Requires Maintainer approval)Related Issues
This is related to RFC #375's section 10.
Checklist
!for breaking changes).Screenshots / Logs (if applicable)