portage-ucp 0.1.0

data/schemas/2026-04-08/schemas/service.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/service.json",
+  "title": "UCP Service",
+  "description": "Service binding for a specific transport. Each transport binding is a separate entry in the service array.",
+  "$defs": {
+    "base": {
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/entity"
+        },
+        {
+          "type": "object",
+          "required": [
+            "transport"
+          ],
+          "properties": {
+            "transport": {
+              "type": "string",
+              "enum": [
+                "rest",
+                "mcp",
+                "a2a",
+                "embedded"
+              ],
+              "description": "Transport protocol for this service binding."
+            },
+            "endpoint": {
+              "type": "string",
+              "format": "uri",
+              "description": "Endpoint URL for this transport binding."
+            }
+          }
+        }
+      ]
+    },
+    "platform_schema": {
+      "title": "Service (Platform Schema)",
+      "description": "Full service declaration for platform-level discovery. All transports require `version`, `spec`, and `transport`. REST, MCP, and embedded additionally require `schema`.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "spec"
+          ]
+        },
+        {
+          "anyOf": [
+            {
+              "properties": {
+                "transport": {
+                  "const": "rest"
+                }
+              },
+              "required": [
+                "schema"
+              ]
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "mcp"
+                }
+              },
+              "required": [
+                "schema"
+              ]
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "a2a"
+                }
+              }
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "embedded"
+                }
+              },
+              "required": [
+                "schema"
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    "business_schema": {
+      "title": "Service (Business Schema)",
+      "description": "Service binding for business/merchant configuration. May override platform endpoints.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "anyOf": [
+            {
+              "properties": {
+                "transport": {
+                  "const": "rest"
+                }
+              },
+              "required": [
+                "endpoint"
+              ]
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "mcp"
+                }
+              },
+              "required": [
+                "endpoint"
+              ]
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "a2a"
+                }
+              },
+              "required": [
+                "endpoint"
+              ]
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "embedded"
+                },
+                "config": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/transports/embedded_config.json"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    "response_schema": {
+      "title": "Service (Response Schema)",
+      "description": "Service binding in API responses. Includes per-resource transport configuration via typed config.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "anyOf": [
+            {
+              "properties": {
+                "transport": {
+                  "const": "rest"
+                }
+              }
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "mcp"
+                }
+              }
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "a2a"
+                }
+              }
+            },
+            {
+              "properties": {
+                "transport": {
+                  "const": "embedded"
+                },
+                "config": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/transports/embedded_config.json"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/cart.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/cart.json",
+  "name": "dev.ucp.shopping.cart",
+  "title": "Cart",
+  "description": "Shopping cart with estimated pricing before checkout. Lightweight pre-purchase exploration with no payment info or complex status states.",
+  "$defs": {
+    "checkout": {
+      "title": "Checkout with Cart",
+      "description": "Checkout extended with cart capability. Adds cart_id to create_checkout for cart-to-checkout conversion.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "cart_id": {
+              "type": "string",
+              "description": "Cart ID to convert to checkout. Business MUST use cart contents (line_items, context, buyer) and MUST ignore overlapping fields in checkout payload.",
+              "ucp_request": {
+                "create": "optional",
+                "update": "omit"
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "type": "object",
+  "required": [
+    "ucp",
+    "id",
+    "line_items",
+    "currency",
+    "totals"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "ucp": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_cart_schema",
+      "ucp_request": "omit"
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique cart identifier.",
+      "ucp_request": {
+        "create": "omit",
+        "update": "required"
+      }
+    },
+    "line_items": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/line_item.json"
+      },
+      "description": "Cart line items. Same structure as checkout. Full replacement on update.",
+      "ucp_request": {
+        "create": "required",
+        "update": "required"
+      }
+    },
+    "context": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/context.json",
+      "description": "Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional"
+      }
+    },
+    "signals": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional"
+      }
+    },
+    "attribution": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional"
+      }
+    },
+    "buyer": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/buyer.json",
+      "description": "Optional buyer information for personalized estimates.",
+      "ucp_request": {
+        "create": "optional",
+        "update": "optional"
+      }
+    },
+    "currency": {
+      "type": "string",
+      "description": "ISO 4217 currency code. Determined by merchant based on context or geo-IP.",
+      "ucp_request": "omit"
+    },
+    "totals": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/totals.json",
+      "description": "Estimated cost breakdown. May be partial if shipping/tax not yet calculable.",
+      "ucp_request": "omit"
+    },
+    "messages": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+      },
+      "description": "Validation messages, warnings, or informational notices.",
+      "ucp_request": "omit"
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/link.json"
+      },
+      "description": "Optional merchant links (policies, FAQs).",
+      "ucp_request": "omit"
+    },
+    "continue_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.",
+      "ucp_request": "omit"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Cart expiry timestamp (RFC 3339). Optional.",
+      "ucp_request": "omit"
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/catalog_lookup.json

@@ -0,0 +1,207 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_lookup.json",
+  "name": "dev.ucp.shopping.catalog.lookup",
+  "title": "Catalog Lookup",
+  "description": "Product/variant lookup by identifier. Supports batch retrieval (lookup_catalog) and single-product detail (get_product).",
+  "type": "object",
+  "$defs": {
+    "lookup_variant": {
+      "description": "Variant with required correlation metadata for lookup responses.",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/variant.json"
+        },
+        {
+          "required": [
+            "inputs"
+          ],
+          "properties": {
+            "inputs": {
+              "type": "array",
+              "items": {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/input_correlation.json"
+              },
+              "minItems": 1,
+              "description": "Which request identifiers resolved to this variant, and how. Each entry maps a request ID to its match type."
+            }
+          }
+        }
+      ]
+    },
+    "lookup_request": {
+      "type": "object",
+      "description": "Request body for catalog lookup.",
+      "required": [
+        "ids"
+      ],
+      "properties": {
+        "ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Identifiers to lookup. Implementations MUST support product ID and variant ID; MAY support secondary identifiers (SKU, handle, etc.)."
+        },
+        "filters": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/search_filters.json",
+          "description": "Filter criteria to narrow returned products and variants. All specified filters combine with AND logic."
+        },
+        "context": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/context.json"
+        },
+        "signals": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json"
+        },
+        "attribution": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json"
+        }
+      }
+    },
+    "lookup_response": {
+      "type": "object",
+      "required": [
+        "ucp",
+        "products"
+      ],
+      "properties": {
+        "ucp": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_catalog_schema"
+        },
+        "products": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              {
+                "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/product.json"
+              },
+              {
+                "properties": {
+                  "variants": {
+                    "items": {
+                      "$ref": "#/$defs/lookup_variant"
+                    }
+                  }
+                }
+              }
+            ]
+          },
+          "description": "Products matching the requested identifiers. May contain fewer items if some identifiers not found, or more if identifiers match multiple products."
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+          },
+          "description": "Errors, warnings, or informational messages about the requested items."
+        }
+      }
+    },
+    "get_product_request": {
+      "type": "object",
+      "description": "Request body for single-product retrieval. Supports interactive variant narrowing via selected and preferences.",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Product or variant identifier. Implementations MUST support product ID and variant ID."
+        },
+        "selected": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/selected_option.json"
+          },
+          "description": "Partial or full option selections for interactive variant narrowing. When provided, response option values include availability signals (available, exists) relative to these selections."
+        },
+        "preferences": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Option names in relaxation priority order. When no exact variant matches all selections, the server drops options from the end of this list first. E.g., ['Color', 'Size'] keeps Color and relaxes Size."
+        },
+        "filters": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/search_filters.json",
+          "description": "Filter criteria to narrow returned variants. All specified filters combine with AND logic."
+        },
+        "context": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/context.json"
+        },
+        "signals": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json"
+        },
+        "attribution": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json"
+        }
+      }
+    },
+    "detail_product": {
+      "description": "A product in a get_product response, extended with effective selections and availability signals on option values.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/product.json"
+        }
+      ],
+      "properties": {
+        "selected": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/selected_option.json"
+          },
+          "description": "Effective option selections that anchor the featured variant and availability signals. Required when the product has configurable options; may be empty or omitted for products with no option axes."
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "values"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "values": {
+                "type": "array",
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/detail_option_value.json"
+                },
+                "minItems": 1
+              }
+            }
+          },
+          "description": "Product options with availability signals relative to the effective selections."
+        }
+      }
+    },
+    "get_product_response": {
+      "type": "object",
+      "required": [
+        "ucp",
+        "product"
+      ],
+      "properties": {
+        "ucp": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_catalog_schema"
+        },
+        "product": {
+          "$ref": "#/$defs/detail_product",
+          "description": "The requested product with full detail. Singular — this is a single-resource operation."
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+          },
+          "description": "Warnings or informational messages about the product (e.g., price recently changed, limited availability)."
+        }
+      }
+    }
+  },
+  "version": "2026-04-08"
+}

data/schemas/2026-04-08/schemas/shopping/catalog_search.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/catalog_search.json",
+  "name": "dev.ucp.shopping.catalog.search",
+  "title": "Catalog Search",
+  "description": "Product catalog search capability.",
+  "type": "object",
+  "$defs": {
+    "search_request": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Free-text search query."
+        },
+        "context": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/context.json"
+        },
+        "signals": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/signals.json"
+        },
+        "attribution": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/attribution.json"
+        },
+        "filters": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/search_filters.json"
+        },
+        "pagination": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/pagination.json#/$defs/request"
+        }
+      }
+    },
+    "search_response": {
+      "type": "object",
+      "required": [
+        "ucp",
+        "products"
+      ],
+      "properties": {
+        "ucp": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/ucp.json#/$defs/response_catalog_schema"
+        },
+        "products": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/product.json"
+          },
+          "description": "Products matching the search criteria."
+        },
+        "pagination": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/pagination.json#/$defs/response"
+        },
+        "messages": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json"
+          },
+          "description": "Errors, warnings, or informational messages about the search results."
+        }
+      }
+    }
+  },
+  "version": "2026-04-08"
+}