portage-ucp 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e47e8018ba5966b67205cb9046efdf0e8f0edbe9ab58eef1e7613232a5b6b27
-  data.tar.gz: c5eaa266f8d88a7fda16a822e0eb0b6aad82465b1e6adbf36abe08e7d2c859c4
+  metadata.gz: a245e863596f643972f10c9be20792055d6bf1d2925b90373571966896ee429a
+  data.tar.gz: ad0008e190d5c865e613b616653a7d5dbd5f6b19166f8f71723e57ae70ef7ce0
 SHA512:
-  metadata.gz: '053845855d29f395fb001b78d13622798aadf54c8dc087c88bdf32a943e65e992e7d6d79a3f9a5c86232ebfb8f65f36eb1137888bd9a806e2ceeeef045a57789'
-  data.tar.gz: 6e1cec328b2d07567d4441340fe177367db3bbe7e094aa93388446cb062ea948e600abeb353dcf31b3833f7f76d2ccc189c275a44ab4c5ea546b94e4f3c152d7
+  metadata.gz: d9a93b39705265b1095da290e5615ddbfcf3d3ea529d9b5863308ad99819c70b11ed77bc9805444a003b78c61bb418d4faa756617148d74b964b88beb90b5330
+  data.tar.gz: c2c95f6b3217ea2c2dc6b86318eaa845677b45c753b707ad2eb17f2ae7599f92fe457f7f82a34d46cfea26f1b5bfa8bc17ff4ee46459c94967c6de5ed6286611

data/CHANGELOG.md

@@ -6,6 +6,16 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-09
+
+Moves the gem to UCP 2026-08-25 (design-log §56-58). Minor-level for a pre-1.0 gem, with breaking config changes below.
+
+- **Breaking: `config.payment_handlers` is now a Hash of `reverse-domain-key => [entry, ...]`, each entry carrying an `id`.** Default is `{}` (was an Array). The manifest emits it as UCP 2026-08-25's keyed `payment_handlers` object with date `version`s; an Array no longer works. `config.services` arrays still work: they are keyed by service name and each entry gets a `version`. A services Hash already keyed by name passes through, keeping an entry's own `version`.
+- **Breaking: the manifest emits `keys` (a JWK Set) at the document root; `ucp.signing_keys` is gone.** Anything reading signing keys from `ucp.signing_keys` must read `keys`. Each key needs a `kid`.
+- **Changed: UCP version is 2026-08-25** (manifest, `WireEnvelope`, `SchemaValidator` default). Capabilities are keyed by reverse-domain name with a date `version` and `schema` URL, and the whole manifest validates against `profile.json#/$defs/business_schema`.
+- **Changed: `FulfillmentOption` `description` is sent as a `description.json` object** rather than a bare string, as 2026-08-25 requires.
+- **Removed: the vendored `schemas/2026-04-08/` tree.** `SchemaValidator.new(version: "2026-04-08")` no longer loads; only `schemas/2026-08-25/` ships. Nothing else in the workspace validated against it (`portage-ucp-client` reads remote profiles without vendored schemas, so stores still serving 2026-04-08 keep working).
+
 ## [0.13.0] - 2026-10-07
 
 - **Added: `Support::CheckoutState` can ask the platform about a checkout this process doesn't track.** An adapter may define a private `platform_checkout_order(checkout_id)` that returns the `Order` its platform placed from that checkout, or nil. `#checkout_status` then reports `completed` for an id with no in-process record, the new `#checkout_order` returns its `OrderConfirmation`, and the new `#checkout_from_platform_order` rebuilds a completed `Checkout` from the order when the platform has already dropped the cart. A found order is cached through `#record_checkout_status`/`#record_order_checkout`; no order, no hook, or a lookup error keeps today's `incomplete`. This lets `portage orders reconcile`, which runs in a new process, see a checkout the shopper paid for in the browser (design-log §55). The `Adapter` contract is unchanged. Minor-level.

data/lib/generators/portage/ucp/install/templates/portage_ucp.rb

@@ -14,8 +14,8 @@ Portage::Ucp.configure do |config|
 
   # config.signer = MySigner.new
   # config.signing_keys = []
-  # config.payment_handlers = []
-  # config.services = []
+  # config.payment_handlers = {} # { "com.example.pay" => [{ id: "..." }] }
+  # config.services = {}        # { "dev.ucp.shopping" => [{ transport: "mcp", endpoint: "..." }] }
   # config.mandate_trusted_keys = []
   # config.require_mandate_signature = false
 end

data/lib/portage/ucp/capabilities/cart.rb

@@ -4,6 +4,7 @@ module Portage
       CART = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.cart",
         version: "1",
+        schema: "shopping/cart.json",
         actions: {
           "create_cart" => :create_cart,
           "get_cart" => :get_cart,

data/lib/portage/ucp/capabilities/catalog.rb

@@ -4,6 +4,7 @@ module Portage
       CATALOG = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.catalog",
         version: "1",
+        schema: "shopping/catalog_search.json",
         actions: { "search_catalog" => :search_catalog, "get_product" => :get_product,
                    "lookup_catalog" => :lookup_catalog }
       )

data/lib/portage/ucp/capabilities/checkout.rb

@@ -4,6 +4,7 @@ module Portage
       CHECKOUT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.checkout",
         version: "1",
+        schema: "shopping/checkout.json",
         actions: {
           "create_checkout" => :create_checkout,
           "get_checkout" => :get_checkout,

data/lib/portage/ucp/capabilities/discount.rb

@@ -8,6 +8,7 @@ module Portage
       DISCOUNT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.discount",
         version: "1",
+        schema: "shopping/discount.json",
         actions: {},
         predicate: :discount_codes_supported?
       )

data/lib/portage/ucp/capabilities/fulfillment.rb

@@ -8,6 +8,7 @@ module Portage
       FULFILLMENT = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.fulfillment",
         version: "1",
+        schema: "shopping/fulfillment.json",
         actions: {},
         predicate: :fulfillment_supported?
       )

data/lib/portage/ucp/capabilities/order.rb

@@ -4,6 +4,7 @@ module Portage
       ORDER = Portage::Ucp::Capability.new(
         name: "dev.ucp.shopping.order",
         version: "1",
+        schema: "shopping/order.json",
         actions: {
           "get_order" => :get_order,
           "cancel_order" => :cancel_order,

data/lib/portage/ucp/capability.rb

@@ -3,7 +3,7 @@ module Portage
     # A named, versioned UCP capability (e.g. "dev.ucp.shopping.catalog") mapping
     # UCP action names to the Adapter methods that back them.
     class Capability
-      attr_reader :name, :version, :actions
+      attr_reader :name, :version, :actions, :schema
 
       # `predicate:` is for extension capabilities like
       # dev.ucp.shopping.discount and dev.ucp.shopping.fulfillment that add a
@@ -11,8 +11,13 @@ module Portage
       # there's no dedicated method whose override signals support, so the
       # adapter exposes a boolean method instead and the capability asks it
       # directly rather than inspecting `actions`.
-      def initialize(name:, version:, actions:, predicate: nil)
+      #
+      # `schema:` is the capability's schema path under a UCP revision's
+      # `schemas/` (e.g. "shopping/checkout.json"); the manifest turns it into
+      # the `schema` URL 2026-08-25 business profiles require.
+      def initialize(name:, version:, actions:, predicate: nil, schema: nil)
         @name = name
+        @schema = schema
         @version = version
         @actions = actions
         @predicate = predicate

data/lib/portage/ucp/configuration.rb

@@ -51,7 +51,7 @@ module Portage
         @authenticator = UnconfiguredAuthenticator.new
         @rate_limiter = NullRateLimiter.new
         @logger = Logger.new($stdout)
-        @payment_handlers = []
+        @payment_handlers = {}
         @signing_keys = []
         @services = []
         @require_mandate_signature = false

data/lib/portage/ucp/manifest.rb

@@ -6,11 +6,12 @@ module Portage
     # Builds the /.well-known/ucp discovery document: protocol version, the
     # business's advertised capabilities (only those the Adapter overrides —
     # see Capability#advertised_for?), payment handlers, signing keys, and the
-    # services array (transport + endpoint, e.g. {transport: "mcp", endpoint:
+    # services (transport + endpoint, e.g. {transport: "mcp", endpoint:
     # "https://..."}) a client needs to find where to actually connect.
     # Signing keys are never generated here — see §9, consumer-provided only.
     class Manifest
-      UCP_VERSION = "2026-04-08".freeze
+      UCP_VERSION = "2026-08-25".freeze
+      SERVICE_KEY = "dev.ucp.shopping".freeze
 
       # @param signer [#kid, #sign] optional. Consumer-provided — the gem never
       #   generates or stores keys itself (§9). `sign(canonical_json_string)`
@@ -35,26 +36,47 @@ module Portage
       # capability name. That is the shape live Shopify UCP rollouts (Casper,
       # Allbirds, Glossier, and 34+ others) serve under their own manifest
       # "version": "2026-08-25", and the shape portage-ucp-client's
-      # Client.discover reads. Only the shape is borrowed: `version` here is
-      # still UCP_VERSION ("2026-04-08"), the spec revision this gem targets.
+      # Client.discover reads. As of 2026-08-25 the JWK Set is `keys` beside
+      # `ucp` (not `ucp.signing_keys`), and `services`, `capabilities` and
+      # `payment_handlers` are objects keyed by reverse-domain name whose
+      # entries carry a date `version` (capabilities also a `schema` URL,
+      # handlers an `id`). `services` still accepts the old bare array of
+      # entries, filed under SERVICE_KEY; `payment_handlers` must already be
+      # a Hash of key => [entry, ...].
       def to_h
         ucp = {
           version: UCP_VERSION,
           business: @business,
-          services: @services,
+          services: keyed(service_hash),
           capabilities: capability_hash,
-          payment_handlers: @payment_handlers,
-          signing_keys: @signing_keys
+          payment_handlers: keyed(@payment_handlers)
         }
         ucp = ucp.merge(signature: sign(ucp)) if @signer
 
-        { ucp: ucp }
+        { ucp: ucp, keys: @signing_keys }
       end
 
       private
 
       def capability_hash
-        @registry.advertised(@adapter).to_h { |capability| [capability.name, [{ version: capability.version }]] }
+        @registry.advertised(@adapter).to_h do |capability|
+          entry = { version: UCP_VERSION }
+          entry[:schema] = "https://ucp.dev/#{UCP_VERSION}/schemas/#{capability.schema}" if capability.schema
+          [capability.name, [entry]]
+        end
+      end
+
+      def service_hash
+        return @services if @services.is_a?(Hash)
+
+        @services.empty? ? {} : { SERVICE_KEY => @services }
+      end
+
+      # Every entry needs a version; the caller's own wins.
+      def keyed(entries_by_key)
+        entries_by_key.to_h do |key, entries|
+          [key, [entries].flatten(1).map { |entry| { version: UCP_VERSION }.merge(entry) }]
+        end
       end
 
       def sign(payload)

data/lib/portage/ucp/schema_validator.rb

@@ -9,12 +9,12 @@ module Portage
     # is the CI-safe equivalent).
     #
     # The vendored tree mirrors https://ucp.dev/<version>/... path-for-path
-    # (schemas/2026-04-08/schemas/shopping/cart.json <->
-    # https://ucp.dev/2026-04-08/schemas/shopping/cart.json), so every $ref
+    # (schemas/2026-08-25/schemas/shopping/cart.json <->
+    # https://ucp.dev/2026-08-25/schemas/shopping/cart.json), so every $ref
     # inside a vendored document — however deeply nested — resolves to another
     # vendored file with a single prefix rewrite, no network access needed.
     class SchemaValidator
-      def initialize(version: "2026-04-08", root: File.join(__dir__, "..", "..", "..", "schemas"))
+      def initialize(version: "2026-08-25", root: File.join(__dir__, "..", "..", "..", "schemas"))
         @base_url = "https://ucp.dev/#{version}/"
         @base_dir = File.expand_path(File.join(root, version))
       end

data/lib/portage/ucp/value_objects.rb

@@ -272,6 +272,8 @@ module Portage
 
     # schemas/shopping/types/fulfillment_option.json — a single priced choice
     # within a FulfillmentGroup (e.g. "Standard Shipping $5", "Express $15").
+    # `description` is a common/types/description.json object
+    # ({"plain"/"html"/"markdown" => ...}); a bare String is sent as `plain`.
     FulfillmentOption = Data.define(:id, :title, :totals, :description, :carrier, :earliest_fulfillment_time,
                                     :latest_fulfillment_time) do
       def initialize(id:, title:, totals:, description: nil, carrier: nil, earliest_fulfillment_time: nil,
@@ -281,7 +283,7 @@ module Portage
 
       def to_wire_h
         h = { "id" => id, "title" => title, "totals" => totals.map(&:to_wire_h) }
-        h["description"] = description if description
+        h["description"] = description.is_a?(String) ? { "plain" => description } : description if description
         h["carrier"] = carrier if carrier
         h["earliest_fulfillment_time"] = earliest_fulfillment_time if earliest_fulfillment_time
         h["latest_fulfillment_time"] = latest_fulfillment_time if latest_fulfillment_time

data/lib/portage/ucp/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Ucp
-    VERSION = "0.13.0".freeze
+    VERSION = "0.14.0".freeze
   end
 end

data/lib/portage/ucp/wire_envelope.rb

@@ -6,7 +6,7 @@ module Portage
     # capability's minimum envelope shape live in one place, not duplicated
     # across value objects.
     module WireEnvelope
-      SPEC_VERSION = "2026-04-08".freeze
+      SPEC_VERSION = "2026-08-25".freeze
 
       ENVELOPES = {
         "dev.ucp.shopping.cart" => -> { { "version" => SPEC_VERSION } },

data/schemas/{2026-04-08 → 2026-08-25}/schemas/capability.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://ucp.dev/2026-04-08/schemas/capability.json",
+  "$id": "https://ucp.dev/2026-08-25/schemas/capability.json",
   "title": "UCP Capability",
   "description": "Schema for UCP capabilities and extensions. Extensions are capabilities with an 'extends' field. Uses reverse-domain naming for governance.",
   "$defs": {
     "base": {
       "allOf": [
         {
-          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/entity"
+          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/entity"
         },
         {
           "type": "object",
@@ -15,14 +15,12 @@
             "extends": {
               "oneOf": [
                 {
-                  "type": "string",
-                  "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                  "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
                 },
                 {
                   "type": "array",
                   "items": {
-                    "type": "string",
-                    "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+                    "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
                   },
                   "minItems": 1
                 }
@@ -50,10 +48,15 @@
     },
     "business_schema": {
       "title": "Capability (Business Schema)",
-      "description": "Capability configuration for business/merchant level. May include business-specific config overrides.",
+      "description": "Capability declaration for business/merchant discovery. Requires the `schema` URL so platforms can fetch and compose it during negotiation; may also include business-specific config overrides.",
       "allOf": [
         {
           "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "schema"
+          ]
         }
       ]
     },
@@ -67,4 +70,4 @@
       ]
     }
   }
-}
+}

data/schemas/2026-08-25/schemas/common/identity_linking.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-08-25/schemas/common/identity_linking.json",
+  "name": "dev.ucp.common.identity_linking",
+  "title": "Identity Linking",
+  "description": "Capability schema for identity linking. Businesses declare the user-authenticated scopes they offer in a flat 'scopes' map. Each key is the OAuth scope string as it appears on the wire ('{capability}:{scope}', e.g. 'dev.ucp.shopping.order:read'). Scope presence implies that the corresponding operations require user authentication. Operations not gated by any listed scope operate at whatever access level the business permits; UCP does not prescribe a default.",
+  "$defs": {
+    "scope_policy": {
+      "type": "object",
+      "title": "Scope Policy",
+      "description": "Per-scope policy and metadata — auth constraints (e.g. min_acr, max_token_age), declarative metadata (e.g. claims produced, consent descriptions), or any other scope-specific configuration. An empty object means user authentication is required with no additional policy. Open for non-breaking extension.",
+      "properties": {
+        "description": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/description.json",
+          "description": "Optional human-readable description of the scope that platforms can use to present and explain context (requirement and value) to the user."
+        }
+      },
+      "additionalProperties": true
+    },
+    "scope_token": {
+      "type": "string",
+      "description": "OAuth scope string formed by joining a capability name and a scope name with a colon: '{capability}:{scope}', e.g. 'dev.ucp.shopping.order:read'. Capability names use reverse-DNS naming; scope names denote the permission granted, defined by each capability's spec (e.g. 'read', 'manage', 'create'). Platforms request these strings verbatim in OAuth 'scope' parameters; issued tokens carry them in the 'scope' claim.",
+      "pattern": "^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9_])?)+:[a-z][a-z0-9_]*$"
+    },
+    "provider": {
+      "type": "object",
+      "title": "Identity Provider",
+      "description": "A trusted identity provider for delegated authentication, keyed by the 'type' discriminator. 'oauth2' denotes an OAuth 2.0 / OIDC authorization server. Future versions MAY define additional types (e.g. wallet attestation) as non-breaking extensions; platforms MUST treat entries whose 'type' they do not support as filtered out (see Provider Selection).",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Provider mechanism discriminator. 'oauth2' for OAuth 2.0 / OIDC authorization servers. Additional values MAY be defined by future versions; the value is an open string, not a closed enum, so unrecognized types remain valid and are filtered at runtime."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "oauth2"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "auth_url"
+            ],
+            "properties": {
+              "auth_url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Base URL for authorization server metadata discovery. Platforms resolve metadata via RFC 8414 (/.well-known/oauth-authorization-server) with OIDC fallback (/.well-known/openid-configuration) on 404."
+              },
+              "required_claims": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true,
+                "description": "OIDC Core §5.1 claim names the business requires in the JWT authorization grant from this provider (e.g. 'email'). Optional pre-filter hint: platforms SHOULD skip this provider during selection when their upstream identity lacks any of the listed claim names. Reactive enforcement at the token endpoint remains mandatory regardless; this field expresses claim presence only, not value constraints."
+              }
+            }
+          }
+        }
+      ],
+      "additionalProperties": true
+    },
+    "dev.ucp.common.identity_linking": {
+      "platform_schema": {
+        "title": "Identity Linking (Platform)",
+        "description": "Platform-level identity linking capability declaration. Platforms advertise support for identity linking; no auth-specific config is required.",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/platform_schema"
+          }
+        ]
+      },
+      "business_schema": {
+        "title": "Identity Linking (Business)",
+        "description": "Business-level identity linking configuration. Businesses declare the user-authenticated scopes they offer in 'config.scopes'.",
+        "allOf": [
+          {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/capability.json#/$defs/business_schema"
+          },
+          {
+            "type": "object",
+            "required": [
+              "config"
+            ],
+            "properties": {
+              "config": {
+                "type": "object",
+                "required": [
+                  "scopes"
+                ],
+                "properties": {
+                  "providers": {
+                    "type": "object",
+                    "description": "Map of trusted external identity providers keyed by reverse-domain identifier. Each key maps to an array of mechanism entries — an IdP namespace MAY offer multiple token acquisition mechanisms. Declares which upstream IdPs the business will accept JWT bearer assertions from for the Accelerated IdP Flow (chaining via RFC 8693 + RFC 7523). This field is additive: direct OAuth against the business domain via RFC 8414 discovery is always available regardless of 'providers' content. Businesses MUST NOT list their own authorization server here — chaining-to-self is degenerate, and direct OAuth covers that path. When absent, empty, or when no listed mechanism is supported by the platform, platforms run direct OAuth on the business domain.",
+                    "propertyNames": {
+                      "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/reverse_domain_name.json"
+                    },
+                    "additionalProperties": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/$defs/provider"
+                      }
+                    }
+                  },
+                  "scopes": {
+                    "type": "object",
+                    "description": "Map of user-authenticated scopes offered by this business. Each key is an OAuth scope string formed as '{capability}:{scope}' (e.g. 'dev.ucp.shopping.order:read'). Scope presence in this map declares that the corresponding operations require a user identity token. Operations not gated by any listed scope operate at whatever access level the business permits; UCP does not prescribe a default. Each value is a per-scope policy object (empty object means user auth required with no additional policy).",
+                    "propertyNames": {
+                      "$ref": "#/$defs/scope_token"
+                    },
+                    "additionalProperties": {
+                      "$ref": "#/$defs/scope_policy"
+                    }
+                  }
+                },
+                "additionalProperties": true
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "version": "2026-08-25"
+}

data/schemas/2026-08-25/schemas/common/location_lookup.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-08-25/schemas/common/location_lookup.json",
+  "name": "dev.ucp.common.location.lookup",
+  "title": "Location Lookup",
+  "description": "Location lookup by identifiers. Supports batch retrieval and single-location detail.",
+  "type": "object",
+  "$defs": {
+    "lookup_location": {
+      "description": "Location with required correlation metadata for lookup responses.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location.json"
+        },
+        {
+          "type": "object",
+          "required": [
+            "inputs"
+          ],
+          "properties": {
+            "inputs": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "id"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "The identifier exactly as supplied in the lookup request.",
+                    "ucp_request": "omit"
+                  }
+                }
+              },
+              "minItems": 1,
+              "description": "Which request identifiers resolved to this Location. Each entry preserves one identifier exactly as supplied in the request.",
+              "ucp_request": "omit"
+            }
+          }
+        }
+      ]
+    },
+    "lookup_request": {
+      "type": "object",
+      "description": "Request body for batch location lookup. The Business resolves and deduplicates `ids` before applying `distance`, `serves`, and every supplied `filters` predicate; all structured predicates combine with AND.",
+      "required": [
+        "ids"
+      ],
+      "properties": {
+        "ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Identifiers of the Locations to look up. The Business MUST support canonical `Location.id` values and MAY support secondary or alias identifiers."
+        },
+        "distance": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_distance.json",
+          "description": "Optional explicit-center radius predicate applied after ID resolution. It combines with `serves` and every supplied `filters` predicate using AND.",
+          "ucp_request": "optional"
+        },
+        "serves": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_serves.json",
+          "description": "Optional authoritative service-target predicate applied after ID resolution. It combines with `distance` and every supplied `filters` predicate using AND.",
+          "ucp_request": "optional"
+        },
+        "filters": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_filter.json"
+        },
+        "context": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/context.json"
+        },
+        "signals": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/signals.json"
+        }
+      }
+    },
+    "lookup_response": {
+      "type": "object",
+      "required": [
+        "ucp",
+        "locations"
+      ],
+      "properties": {
+        "ucp": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/response_location_schema"
+        },
+        "locations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/lookup_location"
+          },
+          "description": "Locations matching the requested identifiers and refinements. May contain fewer Locations if some identifiers do not resolve or their resolved Locations are filtered out, or more if one identifier resolves to multiple Locations. When multiple identifiers resolve to the same Location, one returned Location carries all corresponding `inputs` entries."
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/message.json"
+          },
+          "description": "Errors, warnings, or informational messages about the requested Locations, including `batch_limit_applied` when the Business processes only its configured maximum number of identifiers."
+        }
+      }
+    }
+  },
+  "version": "2026-08-25"
+}

data/schemas/2026-08-25/schemas/common/location_search.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-08-25/schemas/common/location_search.json",
+  "name": "dev.ucp.common.location.search",
+  "title": "Location Search",
+  "description": "Location search capability. Supports natural language queries, distance and serviceability relations, structured filtering including current item availability, and pagination.",
+  "type": "object",
+  "$defs": {
+    "search_request": {
+      "type": "object",
+      "description": "Request body for location search. The `distance` and `serves` relations and every supplied `filters` predicate combine with AND; `query` does not relax them.",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Free-text search query for natural language location search (e.g., 'restaurants near me that deliver', 'hotels with pool')."
+        },
+        "context": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/context.json"
+        },
+        "signals": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/signals.json"
+        },
+        "distance": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_distance.json",
+          "description": "Optional explicit-center radius predicate. When present, it combines with `serves` and every supplied `filters` predicate using AND.",
+          "ucp_request": "optional"
+        },
+        "serves": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_serves.json",
+          "description": "Optional authoritative service-target predicate. When present, it combines with `distance` and every supplied `filters` predicate using AND.",
+          "ucp_request": "optional"
+        },
+        "filters": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location_filter.json"
+        },
+        "pagination": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/pagination.json#/$defs/request"
+        }
+      }
+    },
+    "search_response": {
+      "type": "object",
+      "required": [
+        "ucp",
+        "locations"
+      ],
+      "properties": {
+        "ucp": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/ucp.json#/$defs/response_location_schema"
+        },
+        "locations": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/location.json"
+          },
+          "description": "Locations matching the search criteria."
+        },
+        "pagination": {
+          "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/pagination.json#/$defs/response"
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/message.json"
+          },
+          "description": "Errors, warnings, or informational messages about the search results."
+        }
+      }
+    }
+  },
+  "version": "2026-08-25"
+}