fix(validation): defer relative refs in bulk registration

Allow bulk registration to store schemas whose relative x-gts-ref pointers require explicit validation, while keeping single registration strict. Recognize the validation query alias so callers can request eager semantic checks consistently.

Signed-off-by: Artifizer <artifizer@gmail.com>

Author: Artifizer

gts/src/gts/_server.py

@@ -345,8 +345,11 @@ async def add_entity(
         self,
         body: dict[str, Any] = Body(...),  # noqa: B008 - FastAPI dependency pattern
         validate: bool = Query(False),
+        validation: bool = Query(False),
     ) -> JSONResponse:
-        result = self.ops.add_entity(body, validate=validate)
+        result = self.ops.add_entity(
+            body, validate=validate is True or validation is True
+        )
         status_code = 200 if result.ok else 409 if result.conflict else 422
         return JSONResponse(result.to_dict(), status_code=status_code)
 

gts/src/gts/ops.py

@@ -384,7 +384,10 @@ def reload_from_path(self, path: str | builtins.list[str]) -> None:
         self.store = GtsStore(self._reader)
 
     def add_entity(
-        self, content: dict[str, Any], validate: bool = False
+        self,
+        content: dict[str, Any],
+        validate: bool = False,
+        resolve_relative: bool = True,
     ) -> GtsAddEntityResult:
         entity = GtsEntity(content=content, cfg=self.cfg)
 
@@ -427,7 +430,9 @@ def add_entity(
 
         try:
             if entity.is_schema:
-                self.store.validate_schema_basic(entity.gts_id.id)
+                self.store.validate_schema_basic(
+                    entity.gts_id.id, resolve_relative=resolve_relative
+                )
                 if validate:
                     self.store.validate_schema(entity.gts_id.id)
             elif validate:
@@ -456,7 +461,7 @@ def add_entities(
     ) -> GtsAddEntitiesResult:
         results: list[GtsAddEntityResult] = []
         for it in items:
-            results.append(self.add_entity(it))
+            results.append(self.add_entity(it, resolve_relative=False))
         ok = all(r.ok for r in results)
         return GtsAddEntitiesResult(ok=ok, results=results)
 

gts/src/gts/store.py

@@ -327,7 +327,9 @@ def _validate_schema_ref_targets(
             for index, item in enumerate(schema):
                 self._validate_schema_ref_targets(item, f"{path}[{index}]", visited)
 
-    def _validate_schema_x_gts_refs(self, gts_id: str) -> None:
+    def _validate_schema_x_gts_refs(
+        self, gts_id: str, resolve_relative: bool = True
+    ) -> None:
         """
         Validate a schema's x-gts-ref fields.
 
@@ -342,16 +344,23 @@ def _validate_schema_x_gts_refs(self, gts_id: str) -> None:
         if not schema_entity.is_schema:
             raise ValueError(f"Entity '{schema_id.id}' is not a schema")
 
-        self._validate_schema_x_gts_refs_content(schema_id.id, schema_entity.content)
+        self._validate_schema_x_gts_refs_content(
+            schema_id.id, schema_entity.content, resolve_relative=resolve_relative
+        )
 
     def _validate_schema_x_gts_refs_content(
-        self, gts_id: str, schema_content: dict[str, Any]
+        self,
+        gts_id: str,
+        schema_content: dict[str, Any],
+        resolve_relative: bool = True,
     ) -> None:
         logger.info(f"Validating schema x-gts-ref fields for {gts_id}")
 
         # Validate x-gts-ref constraints in the schema
         x_gts_ref_validator = XGtsRefValidator(store=self)
-        x_gts_ref_errors = x_gts_ref_validator.validate_schema(schema_content)
+        x_gts_ref_errors = x_gts_ref_validator.validate_schema(
+            schema_content, resolve_relative=resolve_relative
+        )
         if x_gts_ref_errors:
             error_messages = [
                 f"{err.field_path}: {err.reason}" for err in x_gts_ref_errors
@@ -624,7 +633,7 @@ def _validate_traits(
                 f"Schema '{gts_id}' trait validation failed: " + "; ".join(errors)
             )
 
-    def validate_schema_basic(self, gts_id: str) -> None:
+    def validate_schema_basic(self, gts_id: str, resolve_relative: bool = True) -> None:
         """Basic schema validation during registration (no chain validation).
 
         Checks:
@@ -661,7 +670,7 @@ def validate_schema_basic(self, gts_id: str) -> None:
         self._validate_schema_refs(schema_content, "")
 
         # 2. Validate x-gts-ref fields
-        self._validate_schema_x_gts_refs(gts_id)
+        self._validate_schema_x_gts_refs(gts_id, resolve_relative=resolve_relative)
 
         # 3. Validate GTS keywords (x-gts-final, x-gts-abstract, placement)
         self._validate_gts_keywords(schema_content)

gts/src/gts/x_gts_ref.py

@@ -222,6 +222,7 @@ def validate_schema(
         schema: dict[str, Any],
         schema_path: str = "",
         root_schema: dict[str, Any] | None = None,
+        resolve_relative: bool = True,
     ) -> list[XGtsRefValidationError]:
         """
         Validate x-gts-ref fields in a schema definition.
@@ -230,6 +231,7 @@ def validate_schema(
             schema: The JSON schema to validate
             schema_path: Current path in schema (for error reporting)
             root_schema: The root schema (for resolving relative refs)
+            resolve_relative: Whether relative refs must resolve during this check
 
         Returns:
             List of validation errors (empty if valid)
@@ -242,6 +244,12 @@ def validate_schema(
             if "x-gts-ref" not in subschema:
                 continue
             ref_value = subschema["x-gts-ref"]
+            if (
+                not resolve_relative
+                and isinstance(ref_value, str)
+                and ref_value.startswith("/")
+            ):
+                continue
             ref_path = f"{path}/x-gts-ref" if path else "x-gts-ref"
             error = self._validate_ref_pattern(ref_value, ref_path, root_schema)
             if error:

tests/test_ops.py

@@ -144,6 +144,16 @@ def test_add_entities_batch(self, ops):
         assert result.ok is True
         assert len(result.results) == 2
 
+    def test_add_entities_defers_relative_pointer_resolution(self, ops):
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "$id": "gts://gts.x.test._.relative.v1~",
+            "properties": {"ref": {"x-gts-ref": "/missing"}},
+        }
+        result = ops.add_entities([schema])
+        assert result.ok is True
+        assert ops.validate_schema("gts.x.test._.relative.v1~").ok is False
+
 
 class TestAddSchemaLegacy:
     def test_add_schema_legacy_success(self, ops):

tests/test_server.py

@@ -75,6 +75,15 @@ def test_add_entity_failure(self, server):
         resp = run(server.add_entity(body={"no": "id"}, validate=False))
         assert resp.status_code == 422
 
+    def test_add_entity_validation_alias(self, server):
+        schema = {
+            **SCHEMA,
+            "$id": "gts://gts.x.test._.relative.v1~",
+            "properties": {"ref": {"x-gts-ref": "/missing"}},
+        }
+        resp = run(server.add_entity(body=schema, validate=False, validation=True))
+        assert resp.status_code == 422
+
     def test_add_changed_entity_conflict(self, server):
         assert run(server.add_entity(body=SCHEMA, validate=False)).status_code == 200
         changed_schema = {**SCHEMA, "properties": {"name": {"type": "integer"}}}

tests/test_store_extra.py

@@ -147,35 +147,27 @@ def test_missing_derived_gts_ref_target_raises(self):
         store = GtsStore(MockGtsReader([target]))
         with pytest.raises(ValueError, match="Unresolvable \\$ref"):
             store._validate_schema_ref_targets(
-                {
-                    "$ref": (
-                        "gts://gts.x.test._.target.v1~"
-                        "x.test._.missing.v1~"
-                    )
-                }
+                {"$ref": ("gts://gts.x.test._.target.v1~x.test._.missing.v1~")}
             )
 
 
 class TestSchemaDependencies:
     def test_ignores_x_gts_ref_in_annotation_data(self):
         store = GtsStore(reader=None)
-        assert list(
-            store._schema_dependencies(
-                {"const": {"x-gts-ref": "gts.x.test._.missing.v1~"}}
+        assert (
+            list(
+                store._schema_dependencies(
+                    {"const": {"x-gts-ref": "gts.x.test._.missing.v1~"}}
+                )
             )
-        ) == []
+            == []
+        )
 
     def test_finds_constraint_under_property_named_x_gts_ref(self):
         store = GtsStore(reader=None)
         assert list(
             store._schema_dependencies(
-                {
-                    "properties": {
-                        "x-gts-ref": {
-                            "x-gts-ref": "gts.x.test._.missing.v1~"
-                        }
-                    }
-                }
+                {"properties": {"x-gts-ref": {"x-gts-ref": "gts.x.test._.missing.v1~"}}}
             )
         ) == [("gts.x.test._.missing.v1~", True)]
 
@@ -256,6 +248,23 @@ def test_invalid_x_gts_ref_raises(self):
         with pytest.raises(Exception, match="x-gts-ref validation failed"):
             store._validate_schema_x_gts_refs("gts.x.test._.foo.v1~")
 
+    def test_basic_validation_can_defer_relative_pointer_resolution(self):
+        schema = _schema_entity(
+            "gts.x.test._.foo.v1~",
+            {
+                "x-gts-traits-schema": {
+                    "properties": {
+                        "ref": {"x-gts-ref": "/x-gts-traits-schema/missingTarget"}
+                    }
+                }
+            },
+        )
+        store = GtsStore(reader=None)
+        store.register(schema)
+        store.validate_schema_basic("gts.x.test._.foo.v1~", resolve_relative=False)
+        with pytest.raises(Exception, match="x-gts-ref validation failed"):
+            store.validate_schema_basic("gts.x.test._.foo.v1~")
+
 
 class TestValidateSchemaChain:
     def test_single_segment_no_parent_ok(self):