portage-ucp 0.1.0

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

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/shopping/types/variant.json",
+  "title": "Variant",
+  "description": "A purchasable variant of a product with specific option selections.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "description",
+    "price"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Global ID (GID) uniquely identifying this variant. Used as item.id in checkout."
+    },
+    "sku": {
+      "type": "string",
+      "description": "Business-assigned identifier for inventory and fulfillment."
+    },
+    "barcodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "type",
+          "value"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Barcode standard. Well-known values: UPC, EAN, ISBN, GTIN, JAN."
+          },
+          "value": {
+            "type": "string",
+            "description": "Barcode value."
+          }
+        }
+      },
+      "description": "Industry-standard product identifiers for cross-reference and correlation."
+    },
+    "handle": {
+      "type": "string",
+      "description": "URL-safe variant handle/slug."
+    },
+    "title": {
+      "type": "string",
+      "description": "Variant display title (e.g., 'Blue / Large')."
+    },
+    "description": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/description.json",
+      "description": "Variant description in one or more formats."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Canonical variant page URL."
+    },
+    "categories": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/category.json"
+      },
+      "description": "Variant categories with optional taxonomy identifiers."
+    },
+    "price": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price.json",
+      "description": "Current selling price."
+    },
+    "list_price": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/price.json",
+      "description": "List price before discounts (for strikethrough display)."
+    },
+    "unit_price": {
+      "type": "object",
+      "description": "Price per standard unit of measurement. MAY be omitted when unit pricing does not apply.",
+      "required": [
+        "amount",
+        "currency",
+        "measure",
+        "reference"
+      ],
+      "properties": {
+        "amount": {
+          "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/amount.json",
+          "description": "Unit price in ISO 4217 minor units. Business MUST return precomputed unit price value: (variant.price / measure.value) * reference.value."
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "description": "ISO 4217 currency code."
+        },
+        "measure": {
+          "type": "object",
+          "description": "Product quantity in packaging (e.g., 750ml bottle).",
+          "required": [
+            "value",
+            "unit"
+          ],
+          "properties": {
+            "value": {
+              "type": "number",
+              "description": "Package quantity."
+            },
+            "unit": {
+              "type": "string",
+              "description": "Unit of measurement."
+            }
+          }
+        },
+        "reference": {
+          "type": "object",
+          "description": "Denominator for unit price display (e.g., per 100ml, per 1kg).",
+          "required": [
+            "value",
+            "unit"
+          ],
+          "properties": {
+            "value": {
+              "type": "integer",
+              "description": "Reference quantity."
+            },
+            "unit": {
+              "type": "string",
+              "description": "Unit of measurement."
+            }
+          }
+        }
+      }
+    },
+    "availability": {
+      "type": "object",
+      "description": "Variant availability for purchase.",
+      "properties": {
+        "available": {
+          "type": "boolean",
+          "description": "Whether this variant can be purchased. See status for fulfillment details."
+        },
+        "status": {
+          "type": "string",
+          "description": "Qualifies available with fulfillment state. Well-known values: `in_stock`, `backorder`, `preorder`, `out_of_stock`, `discontinued`."
+        }
+      }
+    },
+    "options": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/selected_option.json"
+      },
+      "description": "Option values that define this variant (e.g., Color: Blue, Size: Large)."
+    },
+    "media": {
+      "type": "array",
+      "items": {
+        "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/media.json"
+      },
+      "description": "Variant media (images, videos, 3D models). First item is the featured media for listings."
+    },
+    "rating": {
+      "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/rating.json",
+      "description": "Variant rating."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Variant tags for categorization and search."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Business-defined custom data extending the standard variant model."
+    },
+    "seller": {
+      "type": "object",
+      "description": "Optional seller context for this variant.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Seller display name."
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/link.json"
+          },
+          "description": "Seller policy and information links."
+        }
+      }
+    }
+  }
+}

data/schemas/2026-04-08/schemas/shopping/types/warning_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/warning_code.json",
+  "title": "Warning Code",
+  "description": "Warning code identifying the type of warning. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted.",
+  "type": "string",
+  "examples": [
+    "final_sale",
+    "prop65",
+    "fulfillment_changed",
+    "age_restricted"
+  ]
+}

data/schemas/2026-04-08/schemas/transports/embedded_config.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/transports/embedded_config.json",
+  "title": "Embedded Transport Config",
+  "description": "Per-session configuration for embedded transport binding. Allows businesses to vary EP availability and delegations based on cart contents, agent authorization, or policy.",
+  "type": "object",
+  "properties": {
+    "delegate": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Delegations the business allows. At service-level, declares available delegations. In UCP responses, confirms accepted delegations for this session."
+    },
+    "color_scheme": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "light",
+          "dark"
+        ]
+      },
+      "description": "Color schemes the business supports. Hosts use ec_color_scheme query parameter to request a scheme from this list."
+    }
+  }
+}

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

@@ -0,0 +1,364 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ucp.dev/2026-04-08/schemas/ucp.json",
+  "title": "UCP Metadata",
+  "description": "Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.",
+  "$defs": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "UCP version in YYYY-MM-DD format."
+    },
+    "version_constraint": {
+      "type": "object",
+      "description": "Version range requirement with minimum and optional maximum.",
+      "properties": {
+        "min": {
+          "$ref": "#/$defs/version",
+          "description": "Minimum required version (inclusive)."
+        },
+        "max": {
+          "$ref": "#/$defs/version",
+          "description": "Maximum compatible version (inclusive). When absent, no upper bound."
+        }
+      },
+      "required": [
+        "min"
+      ],
+      "additionalProperties": true
+    },
+    "requires": {
+      "type": "object",
+      "description": "Version requirements for extension schemas. Declares minimum (and optionally maximum) protocol and capability versions needed for correct operation.",
+      "properties": {
+        "protocol": {
+          "$ref": "#/$defs/version_constraint",
+          "description": "Required protocol version."
+        },
+        "capabilities": {
+          "type": "object",
+          "description": "Required capability versions, keyed by capability name. Keys must be a subset of the extension's $defs keys.",
+          "propertyNames": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/version_constraint"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "entity": {
+      "type": "object",
+      "description": "Shared foundation for all UCP entities.",
+      "required": [
+        "version"
+      ],
+      "properties": {
+        "version": {
+          "$ref": "#/$defs/version",
+          "description": "Entity version in YYYY-MM-DD format."
+        },
+        "spec": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to human-readable specification document."
+        },
+        "schema": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to JSON Schema defining this entity's structure and payloads."
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this entity instance. Used to disambiguate when multiple instances exist."
+        },
+        "config": {
+          "type": "object",
+          "description": "Entity-specific configuration. Structure defined by each entity's schema.",
+          "additionalProperties": true
+        }
+      }
+    },
+    "base": {
+      "description": "Base UCP metadata with shared properties for all schema types.",
+      "type": "object",
+      "required": [
+        "version"
+      ],
+      "properties": {
+        "version": {
+          "$ref": "#/$defs/version"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "success",
+            "error"
+          ],
+          "default": "success",
+          "description": "Application-level status of the UCP operation."
+        },
+        "services": {
+          "type": "object",
+          "description": "Service registry keyed by reverse-domain name.",
+          "propertyNames": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json"
+          },
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/service.json#/$defs/base"
+            }
+          }
+        },
+        "capabilities": {
+          "type": "object",
+          "description": "Capability registry keyed by reverse-domain name.",
+          "propertyNames": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json"
+          },
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/base"
+            }
+          }
+        },
+        "payment_handlers": {
+          "type": "object",
+          "description": "Payment handler registry keyed by reverse-domain name.",
+          "propertyNames": {
+            "$ref": "https://ucp.dev/2026-04-08/schemas/shopping/types/reverse_domain_name.json"
+          },
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/base"
+            }
+          }
+        }
+      }
+    },
+    "success": {
+      "description": "UCP metadata with status 'success'. Use for response branches that carry the expected payload.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "properties": {
+            "status": {
+              "const": "success"
+            }
+          },
+          "required": [
+            "status"
+          ]
+        }
+      ]
+    },
+    "error": {
+      "description": "UCP metadata with status 'error'. Use for response branches that carry error information.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "properties": {
+            "status": {
+              "const": "error"
+            }
+          },
+          "required": [
+            "status"
+          ]
+        }
+      ]
+    },
+    "platform_schema": {
+      "title": "UCP Platform Schema",
+      "description": "Full UCP metadata for platform-level configuration. Hosted at a URI advertised by the platform in request headers.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "services",
+            "payment_handlers"
+          ],
+          "properties": {
+            "services": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/service.json#/$defs/platform_schema"
+                }
+              }
+            },
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/platform_schema"
+                }
+              }
+            },
+            "payment_handlers": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/platform_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "business_schema": {
+      "title": "UCP Business Schema",
+      "description": "UCP metadata for business/merchant-level configuration. Subset of platform schema with business-specific settings.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "services",
+            "payment_handlers"
+          ],
+          "properties": {
+            "supported_versions": {
+              "type": "object",
+              "description": "Previous protocol versions this business supports, mapped to profile URIs. Businesses that support older protocol versions SHOULD advertise each version and link to its profile. Each URI points to a complete, self-contained profile for that version. When omitted, only `version` is supported.",
+              "propertyNames": {
+                "$ref": "#/$defs/version"
+              },
+              "additionalProperties": {
+                "type": "string",
+                "format": "uri"
+              }
+            },
+            "services": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/service.json#/$defs/business_schema"
+                }
+              }
+            },
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/business_schema"
+                }
+              }
+            },
+            "payment_handlers": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/business_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "response_checkout_schema": {
+      "title": "UCP Checkout Response Schema",
+      "description": "UCP metadata for checkout responses.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "required": [
+            "payment_handlers"
+          ],
+          "properties": {
+            "services": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/service.json#/$defs/response_schema"
+                }
+              }
+            },
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/response_schema"
+                }
+              }
+            },
+            "payment_handlers": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/payment_handler.json#/$defs/response_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "response_order_schema": {
+      "title": "UCP Order Response Schema",
+      "description": "UCP metadata for order responses. No payment handlers needed post-purchase.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "properties": {
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/response_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "response_cart_schema": {
+      "title": "UCP Cart Response Schema",
+      "description": "UCP metadata for cart responses. No payment handlers needed pre-checkout.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "properties": {
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/response_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "response_catalog_schema": {
+      "title": "UCP Catalog Response Schema",
+      "description": "UCP metadata for catalog responses.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/base"
+        },
+        {
+          "properties": {
+            "capabilities": {
+              "additionalProperties": {
+                "items": {
+                  "$ref": "https://ucp.dev/2026-04-08/schemas/capability.json#/$defs/response_schema"
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}