Merge pull request #45 from Artifizer/main

test: Add docs and tests for rejecting plain/wildcard GTS schema IDs

Author: Artifizer

README.md

@@ -1137,6 +1137,8 @@ This section provides **recommended** conventions for embedding GTS identifiers
 
 It is recommended to put the GTS **type identifier** into the JSON Schema `$id` field, using a URI-like form by prepending the `gts://` prefix:
 
+> **Reserved prefix note**: Do **not** place the canonical `gts.` string directly in `$id`. Always wrap the identifier with the `gts://` scheme (for example: `"$id": "gts://gts.x.core.events.type.v1~"`). The raw `gts.` prefix is reserved for canonical identifiers inside the scheme, and mixing it directly into `$id` leads to ambiguity and upload failures.
+
 ```json
 {
   "$id": "gts://gts.x.core.events.type.v1~",
@@ -1147,10 +1149,14 @@ It is recommended to put the GTS **type identifier** into the JSON Schema `$id`
 
 Implementation note: GTS itself defines the canonical identifier string starting with `gts.`. When `$id` is expressed as `gts://...`, implementations should trim the `gts://` prefix and treat the remainder as the canonical GTS identifier for validation, comparison, and registry keys. The `gts://` prefix exists only to make `$id` URI-compatible.
 
+When `$id` starts with `gts://`, the remainder **must** be a valid, wildcard-free GTS identifier (see OP#1 rules). Asterisks and other wildcard tokens are not permitted in schema identifiers.
+
 **JSON Schema (`$ref`)**
 
 It is recommended to make GTS schema references in JSON Schema `$ref` URI-compatible the same way as `$id`, by prepending the `gts://` prefix when `$ref` points at a GTS schema identifier:
 
+> **Note:** Just like `$id`, do not embed raw `gts.` prefixes in `$ref`. Use the URI form (`gts://...`) and ensure the referenced identifier is a valid GTS ID with no wildcard characters.
+
 ```json
 {
   "allOf": [
@@ -1163,6 +1169,8 @@ Note: local JSON Schema references (e.g. `"$ref": "#/definitions/Foo"`, `"$ref":
 
 Implementation note: When `$ref` is expressed as `gts://...`, implementations should trim the `gts://` prefix and treat the remainder as the canonical GTS identifier for resolution, validation, comparison, and registry keys. The `gts://` prefix exists only to make `$ref` URI-compatible.
 
+The post-`gts://` content must therefore parse as a valid GTS identifier with no wildcards; otherwise the schema upload should be rejected.
+
 **JSON instances (well-known vs anonymous)**
 
 - **Well-known instances (named)**: recommended to use a GTS identifier in the `id` field (alternatives: `gtsId`, `gts_id`). Prefer a chained identifier so the **left segment(s)** define the schema/type automatically, and the **rightmost** segment is the instance name.

tests/test_op6_schema_validation.py

@@ -189,6 +189,62 @@ def test_start(self):
     ]
 
 
+class TestCaseTestOp6SchemaValidation_InvalidSchemaIdPrefix(HttpRunner):
+    """OP#6 - Reject JSON Schema identifier values that start with 'gts.'"""
+
+    config = Config(
+        "OP#6 - Schema Validation: reject plain gts prefix in id"
+    ).base_url(get_gts_base_url())
+
+    def test_start(self):
+        super().test_start()
+
+    teststeps = [
+        Step(
+            RunRequest("register schema with plain gts prefix should fail")
+            .post("/entities")
+            .with_params(**{"validate": "true"})
+            .with_json({
+                "$$id": "gts.x.test6.invalid_id.plain_prefix.v1~",
+                "$$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {"id": {"type": "string"}},
+                "required": ["id"]
+            })
+            .validate()
+            .assert_equal("status_code", 422)
+        ),
+    ]
+
+
+class TestCaseTestOp6SchemaValidation_InvalidSchemaIdWildcard(HttpRunner):
+    """OP#6 - Reject JSON Schema identifier with wildcard after gts://"""
+
+    config = Config(
+        "OP#6 - Schema Validation: reject wildcard gts:// id"
+    ).base_url(get_gts_base_url())
+
+    def test_start(self):
+        super().test_start()
+
+    teststeps = [
+        Step(
+            RunRequest("register schema with wildcard gts:// id should fail")
+            .post("/entities")
+            .with_params(**{"validate": "true"})
+            .with_json({
+                "$$id": "gts://gts.x.test6.events.*.v1~",
+                "$$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "properties": {"id": {"type": "string"}},
+                "required": ["id"]
+            })
+            .validate()
+            .assert_equal("status_code", 422)
+        ),
+    ]
+
+
 class TestCaseTestOp6ValidateInstance_NotFound(HttpRunner):
     """OP#6 - Schema Validation: Validate non-existent instance"""
     config = Config("OP#6 - Validate Instance (not found)").base_url(get_gts_base_url())

tests/test_op7_relationship_resolution.py

@@ -133,6 +133,68 @@ def test_start(self):
     ]
 
 
+class TestCaseTestOp7SchemaGraph_RefPlainGtsPrefix(HttpRunner):
+    """OP#7 - Reject $ref that starts with 'gts.' instead of 'gts://'"""
+
+    config = Config("OP#7 - Schema Graph ($$ref plain gts prefix)").base_url(
+        get_gts_base_url()
+    )
+
+    def test_start(self):
+        super().test_start()
+
+    teststeps = [
+        Step(
+            RunRequest("register schema with plain gts. $ref should fail")
+            .post("/entities")
+            .with_params(**{"validate": "true"})
+            .with_json({
+                "$$id": "gts://gts.x.test7.invalid_ref.plain_prefix.v1~",
+                "$$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "allOf": [
+                    {
+                        "$$ref": "gts.x.test7.invalid_ref.plain_prefix.v1~"
+                    }
+                ]
+            })
+            .validate()
+            .assert_equal("status_code", 422)
+        ),
+    ]
+
+
+class TestCaseTestOp7SchemaGraph_RefWildcardGts(HttpRunner):
+    """OP#7 - Reject $ref using wildcards after gts://"""
+
+    config = Config("OP#7 - Schema Graph ($$ref wildcard gts://)").base_url(
+        get_gts_base_url()
+    )
+
+    def test_start(self):
+        super().test_start()
+
+    teststeps = [
+        Step(
+            RunRequest("register schema with wildcard gts:// $ref should fail")
+            .post("/entities")
+            .with_params(**{"validate": "true"})
+            .with_json({
+                "$$id": "gts://gts.x.test7.invalid_ref.wildcard.v1~",
+                "$$schema": "http://json-schema.org/draft-07/schema#",
+                "type": "object",
+                "allOf": [
+                    {
+                        "$$ref": "gts://gts.x.test7.events.*.v1~"
+                    }
+                ]
+            })
+            .validate()
+            .assert_equal("status_code", 422)
+        ),
+    ]
+
+
 class TestCaseTestOp7SchemaGraph_LocalRefAllowed(HttpRunner):
     """OP#7 - Relationship Resolution: Allow local JSON Schema $ref"""
     config = Config("OP#7 - Schema Graph (local $$ref allowed)").base_url(