portage-ucp 0.1.0

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/input_correlation.json",
+  "title": "Input Correlation",
+  "description": "Maps a request identifier to the variant it resolved to, with match semantics.",
+  "type": "object",
+  "required": [
+    "id"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "The identifier from the lookup request that resolved to this variant."
+    },
+    "match": {
+      "type": "string",
+      "description": "How the request identifier resolved to this variant. Well-known values: `exact` (input directly identifies this variant, e.g., variant ID, SKU), `featured` (server selected this variant as representative, e.g., product ID resolved to best match). Businesses MAY implement and provide additional resolution strategies.",
+      "examples": [
+        "exact",
+        "featured"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/item.json",
+  "title": "Item",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "price"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business."
+    },
+    "title": {
+      "type": "string",
+      "description": "Product title.",
+      "ucp_request": "omit"
+    },
+    "price": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+      "description": "Unit price in ISO 4217 minor units.",
+      "ucp_request": "omit"
+    },
+    "image_url": {
+      "type": "string",
+      "description": "Product image URI.",
+      "format": "uri",
+      "ucp_request": "omit"
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/line_item.json",
+  "title": "Line Item",
+  "type": "object",
+  "description": "Line item object. Expected to use the currency of the parent object.",
+  "required": [
+    "id",
+    "item",
+    "quantity",
+    "totals"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "ucp_request": {
+        "create": "omit",
+        "update": "optional"
+      }
+    },
+    "item": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/item.json"
+    },
+    "quantity": {
+      "type": "integer",
+      "description": "Quantity of the item being purchased.",
+      "minimum": 1
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json"
+      },
+      "description": "Line item totals breakdown.",
+      "ucp_request": "omit"
+    },
+    "parent_id": {
+      "type": "string",
+      "description": "Parent line item identifier for any nested structures.",
+      "ucp_request": {
+        "create": "omit",
+        "update": "optional"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/link.json",
+  "title": "Link",
+  "type": "object",
+  "required": [
+    "type",
+    "url"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Type of link. Well-known values: `privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`. Consumers SHOULD handle unknown values gracefully by displaying them using the `title` field or omitting the link."
+    },
+    "url": {
+      "type": "string",
+      "description": "The actual URL pointing to the content to be displayed.",
+      "format": "uri"
+    },
+    "title": {
+      "type": "string",
+      "description": "Optional display text for the link. When provided, use this instead of generating from type."
+    }
+  }
+}

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

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/media.json",
+  "title": "Media",
+  "description": "Product media item (image, video, etc.).",
+  "type": "object",
+  "required": [
+    "type",
+    "url"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "Media type. Well-known values: `image`, `video`, `model_3d`."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to the media resource."
+    },
+    "alt_text": {
+      "type": "string",
+      "description": "Accessibility text describing the media."
+    },
+    "width": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Width in pixels (for images/video)."
+    },
+    "height": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Height in pixels (for images/video)."
+    }
+  }
+}

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

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/message.json",
+  "title": "Message",
+  "type": "object",
+  "description": "Container for error, warning, or info messages.",
+  "oneOf": [
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_error.json"
+    },
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_warning.json"
+    },
+    {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_info.json"
+    }
+  ]
+}

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

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_error.json",
+  "title": "Message Error",
+  "type": "object",
+  "required": [
+    "type",
+    "code",
+    "content",
+    "severity"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "error",
+      "description": "Message type discriminator."
+    },
+    "code": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/error_code.json"
+    },
+    "path": {
+      "type": "string",
+      "description": "RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1])."
+    },
+    "content_type": {
+      "type": "string",
+      "enum": [
+        "plain",
+        "markdown"
+      ],
+      "default": "plain",
+      "description": "Content format, default = plain."
+    },
+    "content": {
+      "type": "string",
+      "description": "Human-readable message."
+    },
+    "severity": {
+      "type": "string",
+      "enum": [
+        "recoverable",
+        "requires_buyer_input",
+        "requires_buyer_review",
+        "unrecoverable"
+      ],
+      "description": "Reflects the resource state and recommended action. 'recoverable': platform can resolve by modifying inputs and retrying via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules. 'unrecoverable': no valid resource exists to act on, retry with new resource or inputs. Errors with 'requires_*' severity contribute to 'status: requires_escalation'."
+    }
+  }
+}

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

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_info.json",
+  "title": "Message Info",
+  "type": "object",
+  "required": [
+    "type",
+    "content"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "info",
+      "description": "Message type discriminator."
+    },
+    "path": {
+      "type": "string",
+      "description": "RFC 9535 JSONPath to the component the message refers to."
+    },
+    "code": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/info_code.json"
+    },
+    "content_type": {
+      "type": "string",
+      "enum": [
+        "plain",
+        "markdown"
+      ],
+      "default": "plain",
+      "description": "Content format, default = plain."
+    },
+    "content": {
+      "type": "string",
+      "description": "Human-readable message."
+    }
+  }
+}

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

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/message_warning.json",
+  "title": "Message Warning",
+  "type": "object",
+  "required": [
+    "type",
+    "code",
+    "content"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "const": "warning",
+      "description": "Message type discriminator."
+    },
+    "path": {
+      "type": "string",
+      "description": "JSONPath (RFC 9535) to related field (e.g., $.line_items[0])."
+    },
+    "code": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/warning_code.json"
+    },
+    "content": {
+      "type": "string",
+      "description": "Human-readable warning message that MUST be displayed."
+    },
+    "content_type": {
+      "type": "string",
+      "enum": [
+        "plain",
+        "markdown"
+      ],
+      "default": "plain",
+      "description": "Content format, default = plain."
+    },
+    "presentation": {
+      "type": "string",
+      "default": "notice",
+      "description": "Rendering contract for this warning. 'notice' (default): platform MUST display, MAY dismiss. 'disclosure': platform MUST display in proximity to the path-referenced component, MUST NOT hide or auto-dismiss. See specification for full contract."
+    },
+    "image_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to a required visual element (e.g., warning symbol, energy class label)."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Reference URL for more information (e.g., regulatory site, registry entry, policy page)."
+    }
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/option_value.json",
+  "title": "Option Value",
+  "description": "A selectable value for a product option.",
+  "type": "object",
+  "required": [
+    "label"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Optional server-assigned identifier for this option value. When present in a selected_option, the server SHOULD use it for matching instead of label."
+    },
+    "label": {
+      "type": "string",
+      "description": "Display text for this option value (e.g., 'Small', 'Blue')."
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/order_confirmation.json",
+  "title": "Order Confirmation",
+  "description": "Order details available at the time of checkout completion.",
+  "type": "object",
+  "required": [
+    "id",
+    "permalink_url"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique order identifier."
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable label for identifying the order. MUST only be provided by the business."
+    },
+    "permalink_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Permalink to access the order on merchant site."
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/order_line_item.json",
+  "title": "Order Line Item",
+  "type": "object",
+  "required": [
+    "id",
+    "item",
+    "quantity",
+    "totals",
+    "status"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Line item identifier."
+    },
+    "item": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/item.json",
+      "description": "Product data (id, title, price, image_url)."
+    },
+    "quantity": {
+      "type": "object",
+      "required": [
+        "total",
+        "fulfilled"
+      ],
+      "properties": {
+        "original": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Quantity from the original checkout."
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Current total active quantity. May differ from original due to post-order modifications (e.g., returns or cancellations)."
+        },
+        "fulfilled": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Quantity fulfilled so far."
+        }
+      },
+      "description": "Quantity tracking for the line item."
+    },
+    "totals": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/total.json"
+      },
+      "description": "Line item totals breakdown."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "processing",
+        "partial",
+        "fulfilled",
+        "removed"
+      ],
+      "description": "Derived status: removed if quantity.total == 0, fulfilled if quantity.total > 0 and quantity.fulfilled == quantity.total, partial if quantity.total > 0 and quantity.fulfilled > 0, otherwise processing."
+    },
+    "parent_id": {
+      "type": "string",
+      "description": "Parent line item identifier for any nested structures."
+    }
+  }
+}

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

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/pagination.json",
+  "title": "Pagination",
+  "description": "Cursor-based pagination for list operations.",
+  "type": "object",
+  "$defs": {
+    "request": {
+      "type": "object",
+      "description": "Pagination parameters for requests.",
+      "properties": {
+        "cursor": {
+          "type": "string",
+          "description": "Opaque cursor from previous response."
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 10,
+          "description": "Requested page size. Implementations MAY clamp to a lower maximum."
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "description": "Pagination information in responses.",
+      "properties": {
+        "cursor": {
+          "type": "string",
+          "description": "Cursor to fetch the next page of results. MUST be present when has_next_page is true."
+        },
+        "has_next_page": {
+          "type": "boolean",
+          "description": "Whether more results are available."
+        },
+        "total_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total number of matching items, if available."
+        }
+      },
+      "required": [
+        "has_next_page"
+      ],
+      "if": {
+        "properties": {
+          "has_next_page": {
+            "const": true
+          }
+        },
+        "required": [
+          "has_next_page"
+        ]
+      },
+      "then": {
+        "required": [
+          "cursor"
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_credential.json",
+  "title": "Payment Credential",
+  "description": "The base definition for any payment credential. Handlers define specific credential types.",
+  "type": "object",
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The credential type discriminator. Specific schemas will constrain this to a constant value."
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json",
+  "title": "Payment Instrument",
+  "description": "The base definition for any payment instrument. It links the instrument to a specific payment handler.",
+  "type": "object",
+  "required": [
+    "id",
+    "handler_id",
+    "type"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "A unique identifier for this instrument instance, assigned by the platform."
+    },
+    "handler_id": {
+      "type": "string",
+      "description": "The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition."
+    },
+    "type": {
+      "type": "string",
+      "description": "The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value."
+    },
+    "billing_address": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/postal_address.json",
+      "description": "The billing address associated with this payment method."
+    },
+    "credential": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/payment_credential.json"
+    },
+    "display": {
+      "type": "object",
+      "description": "Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler."
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "selected_payment_instrument": {
+      "title": "Selected Payment Instrument",
+      "description": "A payment instrument with selection state.",
+      "allOf": [
+        {
+          "$ref": "#"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "selected": {
+              "type": "boolean",
+              "description": "Whether this instrument is selected by the user."
+            }
+          }
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/platform_fulfillment_config.json",
+  "title": "Platform Fulfillment Config",
+  "description": "Platform's fulfillment configuration.",
+  "type": "object",
+  "properties": {
+    "supports_multi_group": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enables multiple groups per method."
+    }
+  }
+}

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

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/postal_address.json",
+  "title": "Postal Address",
+  "type": "object",
+  "properties": {
+    "extended_address": {
+      "type": "string",
+      "description": "An address extension such as an apartment number, C/O or alternative name."
+    },
+    "street_address": {
+      "type": "string",
+      "description": "The street address."
+    },
+    "address_locality": {
+      "type": "string",
+      "description": "The locality in which the street address is, and which is in the region. For example, Mountain View."
+    },
+    "address_region": {
+      "type": "string",
+      "description": "The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division."
+    },
+    "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."
+    },
+    "postal_code": {
+      "type": "string",
+      "description": "The postal code. For example, 94043."
+    },
+    "first_name": {
+      "type": "string",
+      "description": "Optional. First name of the contact associated with the address."
+    },
+    "last_name": {
+      "type": "string",
+      "description": "Optional. Last name of the contact associated with the address."
+    },
+    "phone_number": {
+      "type": "string",
+      "description": "Optional. Phone number of the contact associated with the address."
+    }
+  }
+}