fix: resolve entity local references before inlining (#72)

Recursively resolve same-document $refs on the entity definition (such as #/$defs/version) upon extraction in preprocess_schemas.py before inlining into capability.json, service.json, and payment_handler.json.

This prevents dangling references in preprocessed schemas, enables valid pattern constraints on generated models, and eliminates Version = TypeAliasType("Version", Any).

Fixes #72

Author: damaz91

preprocess_schemas.py

@@ -86,6 +86,37 @@ def resolve_local_ref(ref, root):
     return current
 
 
+def resolve_local_refs(fragment, root, seen=None):
+    """
+    Recursively resolves and inlines local $ref pointers (#/...) within a schema fragment.
+    """
+    if seen is None:
+        seen = set()
+
+    if isinstance(fragment, dict):
+        if "$ref" in fragment:
+            ref = fragment["$ref"]
+            if (
+                isinstance(ref, str)
+                and ref.startswith("#/")
+                and ref not in seen
+            ):
+                target = resolve_local_ref(ref, root)
+                if target is not None:
+                    resolved = copy.deepcopy(target)
+                    resolve_local_refs(resolved, root, seen | {ref})
+                    for k, v in fragment.items():
+                        if k != "$ref":
+                            resolved[k] = v
+                    fragment.clear()
+                    fragment.update(resolved)
+        for v in list(fragment.values()):
+            resolve_local_refs(v, root, seen)
+    elif isinstance(fragment, list):
+        for item in fragment:
+            resolve_local_refs(item, root, seen)
+
+
 # --- Schema Normalization and Flattening ---
 
 
@@ -679,7 +710,10 @@ def main():
     ucp_path = str((target_dir / "ucp.json").resolve())
     entity_def = {}
     if ucp_path in schemas:
-        entity_def = schemas[ucp_path].get("$defs", {}).get("entity", {})
+        entity_def = copy.deepcopy(
+            schemas[ucp_path].get("$defs", {}).get("entity", {})
+        )
+        resolve_local_refs(entity_def, schemas[ucp_path])
     if not entity_def:
         raise ValueError(
             "Entity definition not found! 'ucp.json' must define '$defs.entity'"

src/ucp_sdk/models/schemas/__init__.py

@@ -15,3 +15,4 @@
 # generated by datamodel-codegen
 # pylint: disable=all
 # pyformat: disable
+

src/ucp_sdk/models/schemas/capability.py

@@ -58,56 +58,11 @@
 """
 
 
-Extends2 = TypeAliasType("Extends2", Extends)
-
-
-Extends3Item = TypeAliasType("Extends3Item", Extends1Item)
-
-
-Extends3 = TypeAliasType(
-    "Extends3", Annotated[list[Extends3Item], Field(..., min_length=1)]
-)
-"""
-Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
-"""
-
-
-Extends4 = TypeAliasType("Extends4", Extends)
-
-
-Extends5Item = TypeAliasType("Extends5Item", Extends1Item)
-
-
-Extends5 = TypeAliasType(
-    "Extends5", Annotated[list[Extends5Item], Field(..., min_length=1)]
-)
-"""
-Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
-"""
-
-
-Extends6 = TypeAliasType("Extends6", Extends)
-
-
-Extends7Item = TypeAliasType("Extends7Item", Extends1Item)
-
-
-Extends7 = TypeAliasType(
-    "Extends7", Annotated[list[Extends7Item], Field(..., min_length=1)]
-)
-"""
-Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
-"""
-
-
-Version = TypeAliasType("Version", Any)
-
-
 class Base(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -133,6 +88,20 @@ class Base(BaseModel):
     """
 
 
+Extends2 = TypeAliasType("Extends2", Extends)
+
+
+Extends3Item = TypeAliasType("Extends3Item", Extends1Item)
+
+
+Extends3 = TypeAliasType(
+    "Extends3", Annotated[list[Extends3Item], Field(..., min_length=1)]
+)
+"""
+Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+"""
+
+
 class PlatformSchema(BaseModel):
     """
     Full capability declaration for platform-level discovery. Includes spec/schema URLs for agent fetching.
@@ -141,7 +110,7 @@ class PlatformSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -167,6 +136,20 @@ class PlatformSchema(BaseModel):
     """
 
 
+Extends4 = TypeAliasType("Extends4", Extends)
+
+
+Extends5Item = TypeAliasType("Extends5Item", Extends1Item)
+
+
+Extends5 = TypeAliasType(
+    "Extends5", Annotated[list[Extends5Item], Field(..., min_length=1)]
+)
+"""
+Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+"""
+
+
 class BusinessSchema(BaseModel):
     """
     Capability configuration for business/merchant level. May include business-specific config overrides.
@@ -175,7 +158,7 @@ class BusinessSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -201,6 +184,20 @@ class BusinessSchema(BaseModel):
     """
 
 
+Extends6 = TypeAliasType("Extends6", Extends)
+
+
+Extends7Item = TypeAliasType("Extends7Item", Extends1Item)
+
+
+Extends7 = TypeAliasType(
+    "Extends7", Annotated[list[Extends7Item], Field(..., min_length=1)]
+)
+"""
+Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.
+"""
+
+
 class ResponseSchema(BaseModel):
     """
     Capability reference in responses. Only name/version required to confirm active capabilities.
@@ -209,7 +206,7 @@ class ResponseSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """

src/ucp_sdk/models/schemas/common/__init__.py

@@ -15,3 +15,4 @@
 # generated by datamodel-codegen
 # pylint: disable=all
 # pyformat: disable
+

src/ucp_sdk/models/schemas/payment_handler.py

@@ -33,14 +33,11 @@
 """
 
 
-Version = TypeAliasType("Version", Any)
-
-
 class Base(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -76,7 +73,7 @@ class PlatformSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -112,7 +109,7 @@ class BusinessSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """
@@ -148,7 +145,7 @@ class ResponseSchema(BaseModel):
     model_config = ConfigDict(
         extra="allow",
     )
-    version: Version
+    version: str = Field(..., pattern="^\\d{4}-\\d{2}-\\d{2}$")
     """
     Entity version in YYYY-MM-DD format.
     """