feat(models): update Python SDK schemas for UCP release 2026-08-25

- Update schema preprocessing pipeline for v2026-08-25 response definitions
- Regenerate Pydantic models from UCP release/2026-08-25 JSON schemas
- Restructure models into common, shopping, and transport verticals
- Add Location Search/Lookup, Loyalty, Request Constraints, Permalinks, and Actions models
- Move shared primitives and payment extensions to common namespace
- Bump package version to 0.5.0 in pyproject.toml and update README.md

Author: segiodongo

.codespellignore

@@ -2,3 +2,4 @@ mor
 tok
 fpan
 dpan
+requestor

.github/workflows/governance.yml

@@ -13,23 +13,21 @@ on:
       assigned, 
       unassigned
     ]
-  workflow_run:
-    workflows: ["PR Review Listener"]
-    types: [completed]
+  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
-    with:
-      pr-number: ${{ github.event.pull_request.number }}
-      commit-sha: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}
     secrets:
       # Required: An org-level Read token to read team memberships
       ORG_READ_TOKEN: ${{ secrets.ORG_READ_TOKEN }}

.github/workflows/tests.yml

@@ -54,9 +54,9 @@ jobs:
         with:
           enable-cache: true
       - name: Regenerate models from the pinned spec version
-        # SDK 0.4.x targets UCP 2026-04-08 (see the README compatibility
+        # SDK 0.5.x targets UCP 2026-08-25 (see the README compatibility
         # table). Bump this pin together with the SDK version line.
-        run: ./generate_models.sh 2026-04-08
+        run: ./generate_models.sh 2026-08-25
       - name: Normalize file endings (as pre-commit's end-of-file-fixer does)
         run: |
           python3 - <<'PY'
@@ -72,7 +72,7 @@ jobs:
         run: |
           git add -A -- src/ucp_sdk/models/schemas
           if ! git diff --cached --quiet -- src/ucp_sdk/models/schemas; then
-            echo "::error::Committed models differ from regeneration against the pinned UCP spec. Either the generation pipeline is broken, or the models were edited without regenerating. Run ./generate_models.sh 2026-04-08 and commit the result."
+            echo "::error::Committed models differ from regeneration against the pinned UCP spec. Either the generation pipeline is broken, or the models were edited without regenerating. Run ./generate_models.sh 2026-08-25 and commit the result."
             git --no-pager diff --cached --stat -- src/ucp_sdk/models/schemas
             git --no-pager diff --cached -- src/ucp_sdk/models/schemas
             exit 1

.gitignore

@@ -3,3 +3,5 @@ node_modules/
 __pycache__/
 .venv/
 *.py[cod]
+ucp/
+uv.lock

README.md

@@ -35,17 +35,6 @@ This repository contains the Python SDK for the
 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
 
 To use this SDK in your own project, install it from PyPI:
@@ -71,20 +60,22 @@ from ucp_sdk.models.schemas.shopping.checkout import Checkout
 checkout = Checkout.model_validate(checkout_data)
 
 # Access typed fields
-print(checkout.status)  # "incomplete" | "ready_for_complete" | ...
-print(checkout.currency)  # ISO 4217 currency code
+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 |
+| Package                                 | Description                                                       |
+| --------------------------------------- | ----------------------------------------------------------------- |
+| `ucp_sdk.models.schemas.common`         | Location search/lookup, identity linking, loyalty, payment terms  |
+| `ucp_sdk.models.schemas.common.types`   | Shared primitives (amounts, prices, totals, postal address, etc.) |
+| `ucp_sdk.models.schemas.shopping`       | Checkout, cart, catalog, order, buyer consent, permalink models   |
+| `ucp_sdk.models.schemas.shopping.types` | Line items, adjustments, fulfillments, destinations, attribution  |
+| `ucp_sdk.models.schemas.transports`     | REST, MCP, and embedded protocol bindings                         |
+| `ucp_sdk.models.schemas`                | Service definitions, capabilities, profile, payment handlers      |
 
 ### Validation
 
@@ -133,21 +124,13 @@ uv sync
 ```
 
 Where `<version>` is the version of the UCP specification to use (for example,
-"2026-04-08").
+"2026-08-25").
 
 If no version is specified, the `main` branch of the
 [UCP repo](https://github.com/Universal-Commerce-Protocol/ucp) will be used.
 
 The generated code is automatically formatted using `ruff`.
 
-### Running Tests
-
-Run the schema preprocessing test suite with:
-
-```bash
-uv run python -m unittest discover -s tests -p "test_*.py"
-```
-
 ## Contributing
 
 We welcome community contributions. See our

generate_models.sh

@@ -27,13 +27,6 @@ if ! command -v git &> /dev/null; then
     exit 1
 fi
 
-# Check if uv is installed before cloning or modifying generated files
-if ! command -v uv &> /dev/null; then
-    echo "Error: uv not found."
-    echo "Please install uv: curl -LsSf https://astral.sh/uv/install.sh | sh"
-    exit 1
-fi
-
 # UCP Version to use (if provided, use release/$1 branch; otherwise, use main)
 if [ -z "$1" ]; then
     BRANCH="main"
@@ -53,20 +46,18 @@ OUTPUT_DIR="src/ucp_sdk/models/schemas"
 # Schema directory (relative to this script)
 SCHEMA_DIR="ucp/source/schemas"
 
-# Snapshot the pristine schemas before preprocessing. postprocess_models.py
-# reads array contains/minContains/maxContains from these originals because
-# preprocessing merges allOf branches and a JSON node holds only one contains,
-# so a second contains keyword (e.g. "exactly one total") would otherwise be
-# silently dropped before the post-processor could see it.
-RAW_SCHEMA_DIR="ucp/raw_schemas"
-rm -rf "$RAW_SCHEMA_DIR"
-cp -R "$SCHEMA_DIR" "$RAW_SCHEMA_DIR"
-
 echo "Preprocessing schemas..."
 uv run python preprocess_schemas.py
 
 echo "Generating Pydantic models from preprocessed schemas..."
 
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "Error: uv not found."
+    echo "Please install uv: curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
 # Ensure output directory is clean
 rm -r -f "$OUTPUT_DIR"
 mkdir -p "$OUTPUT_DIR"
@@ -75,7 +66,6 @@ mkdir -p "$OUTPUT_DIR"
 # Run generation using uv
 # We use --use-schema-description to use descriptions from JSON schema as docstrings
 # We use --field-constraints to include validation constraints (regex, min/max, etc.)
-# We use --reuse-model to collapse structurally identical generated types.
 # Note: Formatting is done as a post-processing step.
 uv run \
     --link-mode=copy \
@@ -91,19 +81,25 @@ uv run \
     --enum-field-as-literal all \
     --disable-timestamp \
     --use-double-quotes \
-    --extra-fields=allow \
-    --use-type-alias \
-    --reuse-model \
+    --no-use-annotated \
+    --allow-extra-fields \
     --custom-template-dir templates \
     --additional-imports pydantic.ConfigDict
 
 
-echo "Post-processing generated models (constraints the generator ignores)..."
-uv run python postprocess_models.py || exit 1
+# Normalize file endings (as pre-commit's end-of-file-fixer does)
+python3 - <<'PY'
+from pathlib import Path
+
+for path in Path("src/ucp_sdk/models/schemas").rglob("*.py"):
+    text = path.read_text(encoding="utf-8")
+    fixed = text.rstrip("\n") + "\n" if text.strip() else ""
+    if fixed != text:
+        path.write_text(fixed, encoding="utf-8")
+PY
 
 echo "Formatting generated models..."
 uv run ruff format
 uv run ruff check --fix "$OUTPUT_DIR"
 
-
 echo "Done. Models generated in $OUTPUT_DIR"

preprocess_schemas.py

@@ -141,15 +141,15 @@ def _process_all_of_item(item, node, root, state):
 
     # Extract polymorphic branches (anyOf, oneOf) to keep the node flat
     for poly_key in ["anyOf", "oneOf"]:
-        if poly_key in item:
+        if poly_key in item and isinstance(item[poly_key], list):
             state["poly_branches"].setdefault(poly_key, []).extend(
                 item.pop(poly_key)
             )
 
     # Merge core property definitions and requirements
-    if "properties" in item:
+    if "properties" in item and isinstance(item["properties"], dict):
         state["merged_properties"].update(item["properties"])
-    if "required" in item:
+    if "required" in item and isinstance(item["required"], list):
         for req in item["required"]:
             if req not in state["merged_required"]:
                 state["merged_required"].append(req)
@@ -196,7 +196,7 @@ def merge_all_of_to_node(node, root):
     models if inheritance is flattened at the schema level rather than relying on
     complex 'allOf' chains which can lead to redundant intermediate classes.
     """
-    if "allOf" not in node:
+    if "allOf" not in node or not isinstance(node["allOf"], list):
         return
 
     all_of_sources = node.pop("allOf")
@@ -221,15 +221,19 @@ def distribute_properties_to_branches(node):
     model in Pydantic. Without this, a generated union model might miss required
     common fields if it's treated as a pure 'oneOf' alternative.
     """
-    if "properties" not in node:
+    if "properties" not in node or not isinstance(node["properties"], dict):
         return
 
     base_props = node["properties"]
-    base_req = node.get("required", [])
+    base_req = (
+        node.get("required", [])
+        if isinstance(node.get("required"), list)
+        else []
+    )
     base_type = node.get("type")
 
     for poly_key in ["anyOf", "oneOf"]:
-        if poly_key not in node:
+        if poly_key not in node or not isinstance(node[poly_key], list):
             continue
 
         updated_branches = []
@@ -263,7 +267,7 @@ def flatten_entity_reference(node, entity_definition):
     Replaces $ref to 'ucp.json#/$defs/entity' with actual logic.
     This effectively converts 'Entity' inheritance into direct 'BaseModel' fields.
     """
-    if "allOf" not in node:
+    if "allOf" not in node or not isinstance(node["allOf"], list):
         return
 
     filtered_all_of = []

pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "ucp-sdk"
-version = "0.4.6"
+version = "0.5.0"
 description = "UCP Python SDK"
 readme = "README.md"
 license = {file = "LICENSE"}
 authors = [
+    { name = "Enric Cusell", email = "cusell@google.com" },
     { name = "Federico D'Amato", email = "damaz@google.com" }
 ]
 classifiers = [
@@ -26,14 +27,7 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-    # Exact pins: the model-drift CI job regenerates the models against the
-    # pinned UCP spec and asserts byte-identical output, so the codegen
-    # toolchain must resolve reproducibly. (The floating ">=0.50.0" bound
-    # broke on 2026-08-03: datamodel-code-generator 0.72.0 mis-resolves the
-    # spec's remote $refs and emits incomplete models.) Bump these pins and
-    # regenerate the models in the same PR.
-    "datamodel-code-generator[http]==0.71.0",
-    "ruff==0.16.1",
+    "datamodel-code-generator[http,ruff]>=0.50.0",
 ]
 
 [build-system]
@@ -75,7 +69,10 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.ruff.lint.per-file-ignores]
-"src/ucp_sdk/models/schemas/**/*.py" = ["E501", "D", "N801"]
+"src/ucp_sdk/models/schemas/**/*.py" = ["E501", "D", "N801", "N815"]
+"preprocess_schemas.py" = ["E501", "D"]
+"postprocess_models.py" = ["E501", "D"]
+"tests/**/*.py" = ["E501", "D"]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "B", "C4", "SIM", "N", "UP", "D", "PTH", "T20"]

src/ucp_sdk/__init__.py

@@ -0,0 +1,17 @@
+# 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.
+
+"""UCP Python SDK."""
+
+__version__ = "0.5.0"

src/ucp_sdk/models/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+"""UCP models."""