portage-ucp 0.1.0

data/schemas/2026-04-08/schemas/shopping/types/available_payment_instrument.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/available_payment_instrument.json",
+  "title": "Available Payment Instrument",
+  "description": "An instrument type available from a payment handler with optional constraints.",
+  "type": "object",
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The instrument type identifier (e.g., 'card', 'gift_card'). References an instrument schema's type constant."
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Constraints on this instrument type. Structure depends on instrument type and active capabilities.",
+      "minProperties": 1
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/business_fulfillment_config.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/business_fulfillment_config.json",
+  "title": "Business Fulfillment Config",
+  "description": "Business's fulfillment configuration.",
+  "type": "object",
+  "properties": {
+    "allows_multi_destination": {
+      "type": "object",
+      "description": "Permits multiple destinations per method type.",
+      "properties": {
+        "shipping": {
+          "type": "boolean",
+          "description": "Multiple shipping destinations allowed."
+        },
+        "pickup": {
+          "type": "boolean",
+          "description": "Multiple pickup locations allowed."
+        }
+      },
+      "additionalProperties": false
+    },
+    "allows_method_combinations": {
+      "type": "array",
+      "description": "Allowed method type combinations.",
+      "items": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "shipping",
+            "pickup"
+          ]
+        }
+      }
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/buyer.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/buyer.json",
+  "title": "Buyer",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "first_name": {
+      "type": "string",
+      "description": "First name of the buyer."
+    },
+    "last_name": {
+      "type": "string",
+      "description": "Last name of the buyer."
+    },
+    "email": {
+      "type": "string",
+      "description": "Email of the buyer."
+    },
+    "phone_number": {
+      "type": "string",
+      "description": "E.164 standard."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/category.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/category.json",
+  "title": "Category",
+  "description": "A product category with optional taxonomy identifier.",
+  "type": "object",
+  "required": [
+    "value"
+  ],
+  "properties": {
+    "value": {
+      "type": "string",
+      "description": "Category value or path (e.g., 'Apparel > Shirts', '1604')."
+    },
+    "taxonomy": {
+      "type": "string",
+      "description": "Source taxonomy. Well-known values: `google_product_category`, `shopify`, `merchant`."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/context.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/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,
+  "properties": {
+    "address_country": {
+      "type": "string",
+      "description": "The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example \"US\". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as \"SGP\" or a full country name such as \"Singapore\" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value."
+    },
+    "address_region": {
+      "type": "string",
+      "description": "The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value."
+    },
+    "postal_code": {
+      "type": "string",
+      "description": "The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value."
+    },
+    "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-04-08/schemas/shopping/types/reverse_domain_name.json"
+      }
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/description.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/description.json",
+  "title": "Description",
+  "description": "Description content in one or more formats. At least one format must be provided.",
+  "type": "object",
+  "properties": {
+    "plain": {
+      "type": "string",
+      "description": "Plain text content."
+    },
+    "html": {
+      "type": "string",
+      "description": "HTML-formatted content. Security: Platforms MUST sanitize before rendering—strip scripts, event handlers, and untrusted elements. Treat all rich text as untrusted input."
+    },
+    "markdown": {
+      "type": "string",
+      "description": "Markdown-formatted content."
+    }
+  },
+  "minProperties": 1
+}

data/schemas/2026-04-08/schemas/shopping/types/detail_option_value.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/detail_option_value.json",
+  "title": "Detail Option Value",
+  "description": "An option value with availability signals relative to the current selections. Used in get_product responses where selected context exists.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/option_value.json"
+    }
+  ],
+  "properties": {
+    "available": {
+      "type": "boolean",
+      "description": "Whether a variant matching this value and the current option selections is purchasable."
+    },
+    "exists": {
+      "type": "boolean",
+      "description": "Whether a variant matching this value and the current option selections exists in the catalog."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/error_code.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_code.json",
+  "title": "Error Code",
+  "description": "Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted.",
+  "type": "string",
+  "examples": [
+    "not_found",
+    "out_of_stock",
+    "item_unavailable",
+    "address_undeliverable",
+    "payment_failed",
+    "eligibility_invalid",
+    "identity_required",
+    "insufficient_scope"
+  ]
+}

data/schemas/2026-04-08/schemas/shopping/types/error_response.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_response.json",
+  "title": "Error Response",
+  "description": "Generic error response when business logic prevents resource creation or failed to retrieve resource. Used when no valid resource can be established.",
+  "type": "object",
+  "required": [
+    "ucp",
+    "messages"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "ucp": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/error",
+      "description": "UCP protocol metadata. Status MUST be 'error' for error response."
+    },
+    "messages": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+      },
+      "minItems": 1,
+      "description": "Array of messages describing why the operation failed."
+    },
+    "continue_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL for buyer handoff or session recovery."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/expectation.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/expectation.json",
+  "title": "Expectation",
+  "description": "Buyer-facing fulfillment expectation representing logical groupings of items (e.g., 'package'). Can be split, merged, or adjusted post-order to set buyer expectations for when/how items arrive.",
+  "type": "object",
+  "required": [
+    "id",
+    "line_items",
+    "method_type",
+    "destination"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Expectation identifier."
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "quantity"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Line item ID reference."
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Quantity of this item in this expectation."
+          }
+        }
+      },
+      "description": "Which line items and quantities are in this expectation."
+    },
+    "method_type": {
+      "type": "string",
+      "enum": [
+        "shipping",
+        "pickup",
+        "digital"
+      ],
+      "description": "Delivery method type (shipping, pickup, digital)."
+    },
+    "destination": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/postal_address.json",
+      "description": "Delivery destination address."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable delivery description (e.g., 'Arrives in 5-8 business days')."
+    },
+    "fulfillable_on": {
+      "type": "string",
+      "description": "When this expectation can be fulfilled: 'now' or ISO 8601 timestamp for future date (backorder, pre-order)."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment.json",
+  "title": "Fulfillment",
+  "description": "Container for fulfillment methods and availability.",
+  "type": "object",
+  "ucp_shared_request": true,
+  "properties": {
+    "methods": {
+      "type": "array",
+      "description": "Fulfillment methods for cart items.",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_method.json"
+      }
+    },
+    "available_methods": {
+      "type": "array",
+      "description": "Inventory availability hints.",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_available_method.json"
+      },
+      "ucp_request": "omit"
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_available_method.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_available_method.json",
+  "title": "Fulfillment Available Method",
+  "description": "Inventory availability hint for a fulfillment method type.",
+  "type": "object",
+  "ucp_shared_request": true,
+  "required": [
+    "type",
+    "line_item_ids"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "shipping",
+        "pickup"
+      ],
+      "description": "Fulfillment method type this availability applies to.",
+      "ucp_request": "omit"
+    },
+    "line_item_ids": {
+      "type": "array",
+      "description": "Line items available for this fulfillment method.",
+      "items": {
+        "type": "string"
+      },
+      "ucp_request": "omit"
+    },
+    "fulfillable_on": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "'now' for immediate availability, or ISO 8601 date for future (preorders, transfers).",
+      "ucp_request": "omit"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable availability info (e.g., 'Available for pickup at Downtown Store today').",
+      "ucp_request": "omit"
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_destination.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_destination.json",
+  "title": "Fulfillment Destination",
+  "description": "A destination for fulfillment.",
+  "type": "object",
+  "ucp_shared_request": true,
+  "oneOf": [
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/shipping_destination.json"
+    },
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/retail_location.json"
+    }
+  ]
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_event.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_event.json",
+  "title": "Fulfillment Event",
+  "description": "Append-only fulfillment event representing an actual shipment. References line items by ID.",
+  "type": "object",
+  "required": [
+    "id",
+    "occurred_at",
+    "type",
+    "line_items"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Fulfillment event identifier."
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp when this fulfillment event occurred."
+    },
+    "type": {
+      "type": "string",
+      "description": "Fulfillment event type. Common values include: processing (preparing to ship), shipped (handed to carrier), in_transit (in delivery network), delivered (received by buyer), failed_attempt (delivery attempt failed), canceled (fulfillment canceled), undeliverable (cannot be delivered), returned_to_sender (returned to merchant)."
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "quantity"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Line item ID reference."
+          },
+          "quantity": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Quantity fulfilled in this event."
+          }
+        }
+      },
+      "description": "Which line items and quantities are fulfilled in this event."
+    },
+    "tracking_number": {
+      "type": "string",
+      "description": "Carrier tracking number (required if type != processing)."
+    },
+    "tracking_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to track this shipment (required if type != processing)."
+    },
+    "carrier": {
+      "type": "string",
+      "description": "Carrier name (e.g., 'FedEx', 'USPS')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the shipment status or delivery information (e.g., 'Delivered to front door', 'Out for delivery')."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_group.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_group.json",
+  "title": "Fulfillment Group",
+  "description": "A merchant-generated package/group of line items with fulfillment options.",
+  "type": "object",
+  "required": [
+    "id",
+    "line_item_ids"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Group identifier for referencing merchant-generated groups in updates.",
+      "ucp_request": {
+        "create": "omit",
+        "update": "required"
+      }
+    },
+    "line_item_ids": {
+      "type": "array",
+      "description": "Line item IDs included in this group/package.",
+      "items": {
+        "type": "string"
+      },
+      "ucp_request": "omit"
+    },
+    "options": {
+      "type": "array",
+      "description": "Available fulfillment options for this group.",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_option.json"
+      },
+      "ucp_request": "omit"
+    },
+    "selected_option_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "ID of the selected fulfillment option for this group."
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_method.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_method.json",
+  "title": "Fulfillment Method",
+  "description": "A fulfillment method (shipping or pickup) with destinations and groups.",
+  "type": "object",
+  "required": [
+    "id",
+    "type",
+    "line_item_ids"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique fulfillment method identifier.",
+      "ucp_request": {
+        "create": "omit",
+        "update": "optional"
+      }
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "shipping",
+        "pickup"
+      ],
+      "description": "Fulfillment method type.",
+      "ucp_request": {
+        "create": "required",
+        "update": "optional"
+      }
+    },
+    "line_item_ids": {
+      "type": "array",
+      "description": "Line item IDs fulfilled via this method.",
+      "items": {
+        "type": "string"
+      },
+      "ucp_request": {
+        "create": "optional",
+        "update": "required"
+      }
+    },
+    "destinations": {
+      "type": "array",
+      "description": "Available destinations. For shipping: addresses. For pickup: retail locations.",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_destination.json"
+      }
+    },
+    "selected_destination_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "ID of the selected destination."
+    },
+    "groups": {
+      "type": "array",
+      "description": "Fulfillment groups for selecting options. Agent sets selected_option_id on groups to choose shipping method.",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_group.json"
+      }
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/fulfillment_option.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/fulfillment_option.json",
+  "title": "Fulfillment Option",
+  "description": "A fulfillment option within a group (e.g., Standard Shipping $5, Express $15).",
+  "type": "object",
+  "ucp_shared_request": true,
+  "required": [
+    "id",
+    "title",
+    "totals"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique fulfillment option identifier.",
+      "ucp_request": "omit"
+    },
+    "title": {
+      "type": "string",
+      "description": "Short label (e.g., 'Express Shipping', 'Curbside Pickup').",
+      "ucp_request": "omit"
+    },
+    "description": {
+      "type": "string",
+      "description": "Complete context for buyer decision (e.g., 'Arrives Dec 12-15 via FedEx').",
+      "ucp_request": "omit"
+    },
+    "carrier": {
+      "type": "string",
+      "description": "Carrier name (for shipping).",
+      "ucp_request": "omit"
+    },
+    "earliest_fulfillment_time": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Earliest fulfillment date.",
+      "ucp_request": "omit"
+    },
+    "latest_fulfillment_time": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Latest fulfillment date.",
+      "ucp_request": "omit"
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json"
+      },
+      "description": "Fulfillment option totals breakdown.",
+      "ucp_request": "omit"
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/info_code.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/info_code.json",
+  "title": "Info Code",
+  "description": "Info code identifying the type of informational message. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted.",
+  "type": "string",
+  "examples": [
+    "identity_optional",
+    "signal",
+    "free_shipping",
+    "not_found"
+  ]
+}