portage-ucp 0.1.0

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/price.json",
+  "title": "Price",
+  "description": "Price with explicit currency.",
+  "type": "object",
+  "required": [
+    "amount",
+    "currency"
+  ],
+  "properties": {
+    "amount": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+      "description": "Amount in ISO 4217 minor units. Use 0 for free items."
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').",
+      "pattern": "^[A-Z]{3}$"
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/price_filter.json",
+  "title": "Price Filter",
+  "description": "Price range filter denominated in context.currency. When context.currency matches the presentment currency, businesses apply the filter directly. When it differs, businesses SHOULD convert filter values to the presentment currency before applying; if conversion is not supported, businesses MAY ignore the filter and SHOULD indicate this via a message. When context.currency is absent, filter denomination is ambiguous and businesses MAY ignore it.",
+  "type": "object",
+  "properties": {
+    "min": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+      "description": "Minimum price in ISO 4217 minor units."
+    },
+    "max": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+      "description": "Maximum price in ISO 4217 minor units."
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/price_range.json",
+  "title": "Price Range",
+  "description": "A price range representing minimum and maximum values (e.g., across product variants).",
+  "type": "object",
+  "required": [
+    "min",
+    "max"
+  ],
+  "properties": {
+    "min": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price.json",
+      "description": "Minimum price in the range."
+    },
+    "max": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price.json",
+      "description": "Maximum price in the range."
+    }
+  }
+}

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

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/product.json",
+  "title": "Product",
+  "description": "A product in the catalog with variants and options.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "description",
+    "price_range",
+    "variants"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Global ID (GID) uniquely identifying this product."
+    },
+    "handle": {
+      "type": "string",
+      "description": "URL-safe slug for SEO-friendly URLs (e.g., 'blue-runner-pro'). Use id for stable API references."
+    },
+    "title": {
+      "type": "string",
+      "description": "Product title."
+    },
+    "description": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/description.json",
+      "description": "Product description in one or more formats."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical product page URL."
+    },
+    "categories": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/category.json"
+      },
+      "description": "Product categories with optional taxonomy identifiers."
+    },
+    "price_range": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price_range.json",
+      "description": "Price range across all variants."
+    },
+    "list_price_range": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price_range.json",
+      "description": "List price range before discounts (for strikethrough display)."
+    },
+    "media": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/media.json"
+      },
+      "description": "Product media (images, videos, 3D models). First item is the featured media for listings."
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/product_option.json"
+      },
+      "description": "Product options (Size, Color, etc.)."
+    },
+    "variants": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/variant.json"
+      },
+      "minItems": 1,
+      "description": "Purchasable variants of this product. First item is the featured variant for listings."
+    },
+    "rating": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/rating.json",
+      "description": "Aggregate product rating."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Product tags for categorization and search."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Business-defined custom data extending the standard product model."
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/product_option.json",
+  "title": "Product Option",
+  "description": "A product option such as size, color, or material.",
+  "type": "object",
+  "required": [
+    "name",
+    "values"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Option name (e.g., 'Size', 'Color')."
+    },
+    "values": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/option_value.json"
+      },
+      "minItems": 1,
+      "description": "Available values for this option."
+    }
+  }
+}

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

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/rating.json",
+  "title": "Rating",
+  "description": "Product rating aggregate.",
+  "type": "object",
+  "required": [
+    "value",
+    "scale_max"
+  ],
+  "properties": {
+    "value": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Average rating value."
+    },
+    "scale_min": {
+      "type": "number",
+      "minimum": 0,
+      "default": 1,
+      "description": "Minimum value on the rating scale (e.g., 1 for 1-5 stars)."
+    },
+    "scale_max": {
+      "type": "number",
+      "minimum": 1,
+      "description": "Maximum value on the rating scale (e.g., 5 for 5-star)."
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of reviews contributing to the rating."
+    }
+  }
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/retail_location.json",
+  "title": "Retail Location",
+  "description": "A pickup location (retail store, locker, etc.).",
+  "type": "object",
+  "ucp_shared_request": true,
+  "required": [
+    "id",
+    "name"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique location identifier.",
+      "ucp_request": "omit"
+    },
+    "name": {
+      "type": "string",
+      "description": "Location name (e.g., store name)."
+    },
+    "address": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/postal_address.json",
+      "description": "Physical address of the location."
+    }
+  }
+}

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

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json",
+  "title": "Reverse Domain Name",
+  "description": "Reverse-domain identifier used for collision-safe namespacing of capabilities, services, handlers, eligibility claims, and extension-contributed keys. Must contain at least two dot-separated segments (e.g., 'dev.ucp.shopping.checkout', 'com.example.loyalty_gold').",
+  "type": "string",
+  "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"
+}

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

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/search_filters.json",
+  "title": "Search Filters",
+  "description": "Filter criteria to narrow search results. All specified filters combine with AND logic.",
+  "type": "object",
+  "properties": {
+    "categories": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Filter by product categories (OR logic — matches products in any listed categories). Values match against the value field in product category entries. Valid values can be discovered from the categories field in search results, merchant documentation, or standard taxonomies that businesses may align with."
+    },
+    "price": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price_filter.json"
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/selected_option.json",
+  "title": "Selected Option",
+  "description": "A specific option selection on a variant (e.g., Size: Large).",
+  "type": "object",
+  "required": [
+    "name",
+    "label"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Option name (e.g., 'Size')."
+    },
+    "id": {
+      "type": "string",
+      "description": "Optional option value identifier from option_value.id. When present, the server SHOULD use it for matching; name and label remain required for display."
+    },
+    "label": {
+      "type": "string",
+      "description": "Selected option label (e.g., 'Large')."
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/shipping_destination.json",
+  "title": "Shipping Destination",
+  "description": "Shipping destination.",
+  "type": "object",
+  "ucp_shared_request": true,
+  "allOf": [
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/postal_address.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "ID specific to this shipping destination.",
+          "ucp_request": "optional"
+        }
+      },
+      "required": [
+        "id"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json",
+  "title": "Signals",
+  "description": "Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.",
+  "type": "object",
+  "propertyNames": {
+    "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$",
+    "description": "Reverse-domain identifier (e.g., dev.ucp.buyer_ip, com.example.device_id)."
+  },
+  "properties": {
+    "dev.ucp.buyer_ip": {
+      "type": "string",
+      "description": "Client's IP address (IPv4 or IPv6)."
+    },
+    "dev.ucp.user_agent": {
+      "type": "string",
+      "description": "Client's HTTP User-Agent header or equivalent."
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/signed_amount.json",
+  "title": "Signed Amount",
+  "description": "Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).",
+  "type": "integer"
+}

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

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json",
+  "title": "Total",
+  "description": "A cost breakdown entry with a category, amount, and optional display text.",
+  "type": "object",
+  "required": [
+    "type",
+    "amount"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.",
+      "ucp_request": "omit"
+    },
+    "display_text": {
+      "type": "string",
+      "description": "Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').",
+      "ucp_request": "omit"
+    },
+    "amount": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signed_amount.json",
+      "ucp_request": "omit"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "discount",
+              "items_discount"
+            ]
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "properties": {
+          "amount": {
+            "exclusiveMaximum": 0
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "enum": [
+              "subtotal",
+              "fulfillment",
+              "tax",
+              "fee"
+            ]
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "properties": {
+          "amount": {
+            "minimum": 0
+          }
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/totals.json",
+  "title": "Totals",
+  "description": "Pricing breakdown provided by the business. MUST contain exactly one subtotal and one total entry. Detail types (tax, fee, discount, fulfillment) may appear multiple times for itemization. Platforms MUST render all entries in order using display_text and amount.",
+  "type": "array",
+  "items": {
+    "allOf": [
+      {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json"
+      },
+      {
+        "type": "object",
+        "properties": {
+          "lines": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "display_text",
+                "amount"
+              ],
+              "properties": {
+                "display_text": {
+                  "type": "string",
+                  "description": "Human-readable label for this sub-line."
+                },
+                "amount": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signed_amount.json"
+                }
+              },
+              "description": "Sub-line entry. Additional metadata MAY be included."
+            },
+            "description": "Optional itemized breakdown. The parent entry is always rendered; lines are supplementary. Sum of line amounts MUST equal the parent entry amount.",
+            "ucp_request": "omit"
+          }
+        }
+      },
+      {
+        "if": {
+          "properties": {
+            "type": {
+              "not": {
+                "enum": [
+                  "subtotal",
+                  "items_discount",
+                  "discount",
+                  "fulfillment",
+                  "tax",
+                  "fee",
+                  "total"
+                ]
+              }
+            }
+          },
+          "required": [
+            "type"
+          ]
+        },
+        "then": {
+          "required": [
+            "display_text"
+          ]
+        }
+      }
+    ]
+  },
+  "allOf": [
+    {
+      "contains": {
+        "properties": {
+          "type": {
+            "const": "subtotal"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "minContains": 1,
+      "maxContains": 1
+    },
+    {
+      "contains": {
+        "properties": {
+          "type": {
+            "const": "total"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "minContains": 1,
+      "maxContains": 1
+    }
+  ]
+}