Merge branch 'main' into u/xiaoxuan/fix-rewrite-ref-one-of

Author: damaz91

.github/CODEOWNERS

@@ -0,0 +1,33 @@
+---
+name: PR Governance
+
+on:
+  pull_request_target:
+    types: [
+      opened, 
+      synchronize, 
+      reopened, 
+      ready_for_review, 
+      review_requested, 
+      review_request_removed, 
+      assigned, 
+      unassigned
+    ]
+  pull_request_review:
+    types: [submitted, dismissed]
+
+jobs:
+  governance:
+    name: Reviews
+    # skip for draft PRs
+    if: github.event.pull_request.draft == false
+    permissions:
+      statuses: write
+      contents: read
+      pull-requests: read
+    # Use the reusable workflow defined in the central governance repository
+    # zizmor: ignore[ref-confusion]
+    uses: Universal-Commerce-Protocol/.github/.github/workflows/reusable-governance.yml@main
+    secrets:
+      # Required: An org-level Read token to read team memberships
+      ORG_READ_TOKEN: ${{ secrets.ORG_READ_TOKEN }}

.github/workflows/governance.yml

@@ -24,8 +24,11 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-python@v5
+    - uses: actions/checkout@v5
+    - uses: actions/setup-python@v6
       with:
         python-version: '3.x'
     - uses: pre-commit/action@v3.0.1
+      env:
+        # workaround for pre-commit/action not being updated to node24
+        FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

.github/workflows/linter.yml

@@ -18,11 +18,11 @@ jobs:
       contents: read
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       # Installs uv (and manages Python automatically)
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v8.2.0
         with:
           enable-cache: true
 

.github/workflows/release.yml

@@ -22,33 +22,103 @@
   <b>Official Python library for the Universal Commerce Protocol (UCP).</b>
 </p>
 
+<p align="center">
+  <a href="https://pypi.org/project/ucp-sdk/"><img src="https://img.shields.io/pypi/v/ucp-sdk" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/ucp-sdk/"><img src="https://img.shields.io/pypi/pyversions/ucp-sdk" alt="Python versions"></a>
+  <a href="https://github.com/Universal-Commerce-Protocol/python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Universal-Commerce-Protocol/python-sdk" alt="License"></a>
+</p>
+
 ## Overview
 
 This repository contains the Python SDK for the
 [Universal Commerce Protocol (UCP)](https://ucp.dev). It provides Pydantic
 models for UCP schemas, making it easy to build UCP-compliant applications in
 Python.
 
+### UCP Version Compatibility
+
+Each version of the Python SDK is generated against a specific version of the
+UCP schema:
+
+| SDK Version       | UCP Schema Version |
+| ----------------- | ------------------ |
+| **`0.4.x`**       | **`2026-04-08`**   |
+| `0.3.x`           | `2026-01-23`       |
+| `0.2.x` / `0.1.x` | `2026-01-11`       |
+
 ## Installation
 
-For now, you can install the SDK using the following commands:
+To use this SDK in your own project, install it from PyPI:
 
 ```bash
-# Clone the repository
-git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
+pip install ucp-sdk
+```
 
-# Navigate to the directory
-cd python-sdk
+Or, if you are managing your project with [uv](https://docs.astral.sh/uv/):
 
-# Install dependencies
-uv sync
+```bash
+uv add ucp-sdk
+```
+
+## Usage
+
+The example below parses a UCP checkout response and reads typed fields:
+
+```python
+from ucp_sdk.models.schemas.shopping.checkout import Checkout
+
+# Parse a UCP checkout response
+checkout = Checkout.model_validate(checkout_data)
+
+# Access typed fields
+print(checkout.status)       # "incomplete" | "ready_for_complete" | ...
+print(checkout.currency)     # ISO 4217 currency code
+for item in checkout.line_items:
+    print(f"{item.item.title}: {item.quantity}")
+```
+
+### Available model packages
+
+| Package                                 | Description                                         |
+| --------------------------------------- | --------------------------------------------------- |
+| `ucp_sdk.models.schemas.shopping`       | Checkout, cart, catalog, order, payment models      |
+| `ucp_sdk.models.schemas.shopping.types` | Line items, totals, buyer, fulfillment, signals     |
+| `ucp_sdk.models.schemas.transports`     | REST, MCP, and embedded protocol bindings           |
+| `ucp_sdk.models.schemas`                | Service definitions, capabilities, payment handlers |
+
+### Validation
+
+All models support Pydantic validation and serialization:
+
+```python
+from pydantic import ValidationError
+from ucp_sdk.models.schemas.shopping.checkout import Checkout
+
+# Validate data against UCP schemas
+try:
+    checkout = Checkout.model_validate(checkout_data)
+    # Serialize to JSON-compatible dict
+    checkout_dict = checkout.model_dump(exclude_none=True)
+except ValidationError as e:
+    print(e.errors())
 ```
 
 ## Development
 
 ### Prerequisites
 
-This project uses `uv` for dependency management.
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
+cd python-sdk
+
+# Install dependencies
+uv sync
+```
 
 ### Generating Pydantic Models
 
@@ -63,7 +133,7 @@ uv sync
 ```
 
 Where `<version>` is the version of the UCP specification to use (for example,
-"2026-01-23").
+"2026-04-08").
 
 If no version is specified, the `main` branch of the
 [UCP repo](https://github.com/Universal-Commerce-Protocol/ucp) will be used.

README.md

@@ -1,4 +1,18 @@
 #!/bin/bash
+# Copyright 2026 UCP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Generate Pydantic models from UCP JSON Schemas
 
 # Ensure we are in the script's directory

generate_models.sh

@@ -306,12 +306,18 @@ def eval_prop_inclusion(name, data, op, base_required):
         include = False
     elif marker == "required":
         is_required = True
+    elif marker == "optional":
+        # A simple string "optional" marker overrides the base schema's required list for all operations.
+        is_required = False
     elif isinstance(marker, dict):
         val = marker.get(op)
         if val == "omit" or val is None:
             include = False
         elif val == "required":
             is_required = True
+        elif val == "optional":
+            # Override base schema's required list when a field is explicitly marked optional for a specific operation.
+            is_required = False
 
     return include, is_required
 
@@ -337,7 +343,7 @@ def update_variant_identity(variant_schema, op, stem):
 def rewrite_refs_to_variants(root, op, file_path, variant_needs):
     """
     Walks a schema tree and updates external links to point to variant files.
-    Example: product.json -> product_create_request.json
+    Example: product.json -> product_create_request.json.
     """
     for node in iter_nodes(root):
         if isinstance(node, dict) and "$ref" in node:
@@ -516,7 +522,7 @@ def main():
     1. Pass 1: Local flattening (allOf) and discovery of needed variants
     2. metadata normalization: unifies ucp properties
     3. Pass 2: Transitive propagation (ensuring matched variants for linked schemas)
-    4. Pass 3: Variant file generation (*_request.json)
+    4. Pass 3: Variant file generation (*_request.json).
     """
     target_dir = Path(
         sys.argv[1] if len(sys.argv) > 1 else "ucp/source/schemas"

preprocess_schemas.py

@@ -1,6 +1,6 @@
 [project]
 name = "ucp-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "UCP Python SDK"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -68,6 +68,9 @@ indent-style = "space"
 skip-magic-trailing-comma = false
 line-ending = "auto"
 
+[tool.ruff.lint.per-file-ignores]
+"src/ucp_sdk/models/schemas/**/*.py" = ["E501", "D"]
+
 [tool.ruff.lint]
 select = ["E", "F", "W", "B", "C4", "SIM", "N", "UP", "D", "PTH", "T20"]
 ignore = ["D212", "D200"]