Merge pull request #7 from Artifizer/main

feat: support GTS spec v0.5 - x-gts-ref, get entity by ID, validation parameter

Author: Artifizer

README.md

@@ -27,10 +27,10 @@ See details in [gts/README.md](gts/README.md)
 
 Other GTS spec [Reference Implementation](https://github.com/globaltypesystem/gts-spec/blob/main/README.md#9-reference-implementation-recommendations) recommended features support:
 
-- [ ] **In-memory entities registry** - simple GTS entities registry with optional GTS references validation on entity registration
+- [x] **In-memory entities registry** - simple GTS entities registry with optional GTS references validation on entity registration
 - [x] **CLI** - command-line interface for all GTS operations
 - [x] **Web server** - a non-production web-server with REST API for the operations processing and testing
-- [ ] **x-gts-ref support** - to support special GTS entity reference annotation in schemas
+- [x] **x-gts-ref support** - to support special GTS entity reference annotation in schemas
 - [ ] **YAML support** - to support YAML files (*.yml, *.yaml) as input files
 - [ ] **TypeSpec support** - add [typespec.io](https://typespec.io/) files (*.tsp) support
 - [ ] **UUID for instances** - to support UUID as ID in JSON instances

gts/openapi.json

@@ -50,6 +50,18 @@
       "post": {
         "summary": "Register a single entity (object or schema)",
         "operationId": "add_entity_entities_post",
+        "parameters": [
+          {
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "title": "Validate",
+              "default": false
+            },
+            "name": "validate",
+            "in": "query"
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
@@ -83,6 +95,46 @@
         }
       }
     },
+    "/entities/{gts_id}": {
+      "get": {
+        "summary": "Get a specific entity by GTS ID",
+        "operationId": "get_entity_entities__gts_id__get",
+        "parameters": [
+          {
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Gts Id"
+            },
+            "name": "gts_id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "title": "Response Get Entity Entities  Gts Id  Get"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/entities/bulk": {
       "post": {
         "summary": "Register multiple entities",

gts/src/gts/ops.py

@@ -134,6 +134,28 @@ def to_dict(self) -> Dict[str, Any]:
         }
 
 
+@dataclass
+class GtsGetEntityResult:
+    """Result of getting a single entity."""
+    ok: bool
+    id: str = ""
+    schema_id: Optional[str] = None
+    is_schema: bool = False
+    content: Any = None
+    error: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {"ok": self.ok}
+        if self.ok:
+            result["id"] = self.id
+            result["schema_id"] = self.schema_id
+            result["is_schema"] = self.is_schema
+            result["content"] = self.content
+        else:
+            result["error"] = self.error
+        return result
+
+
 @dataclass
 class GtsEntitiesListResult:
     """Result of listing entities."""
@@ -265,11 +287,41 @@ def reload_from_path(self, path: str | List[str]) -> None:
         self._reader = GtsFileReader(self.path, cfg=self.cfg)
         self.store = GtsStore(self._reader)
 
-    def add_entity(self, content: Dict[str, Any]) -> GtsAddEntityResult:
+    def add_entity(
+        self,
+        content: Dict[str, Any],
+        validate: bool = False
+    ) -> GtsAddEntityResult:
         entity = JsonEntity(content=content, cfg=self.cfg)
         if not entity.gts_id:
-            return GtsAddEntityResult(ok=False, error="Unable to detect GTS ID in entity")
+            return GtsAddEntityResult(
+                ok=False,
+                error="Unable to detect GTS ID in entity"
+            )
+
+        # Register the entity first
         self.store.register(entity)
+
+        # Always validate schemas
+        if entity.is_schema:
+            try:
+                self.store.validate_schema(entity.gts_id.id)
+            except Exception as e:
+                return GtsAddEntityResult(
+                    ok=False,
+                    error=f"Validation failed: {str(e)}"
+                )
+
+        # If validation is requested, validate the instance as well
+        if validate and not entity.is_schema:
+            try:
+                self.store.validate_instance(entity.gts_id.id)
+            except Exception as e:
+                return GtsAddEntityResult(
+                    ok=False,
+                    error=f"Validation failed: {str(e)}"
+                )
+
         return GtsAddEntityResult(
             ok=True,
             id=entity.gts_id.id,
@@ -337,6 +389,23 @@ def validate_instance(self, gts_id: str) -> GtsValidationResult:
         except Exception as e:
             return GtsValidationResult(id=gts_id, ok=False, error=str(e))
 
+    def validate_schema(self, gts_id: str) -> GtsValidationResult:
+        try:
+            self.store.validate_schema(gts_id)
+            return GtsValidationResult(id=gts_id, ok=True)
+        except Exception as e:
+            return GtsValidationResult(id=gts_id, ok=False, error=str(e))
+
+    def validate_entity(self, gts_id: str) -> GtsValidationResult:
+        try:
+            if gts_id.endswith("~"):
+                self.store.validate_schema(gts_id)
+            else:
+                self.store.validate_instance(gts_id)
+            return GtsValidationResult(id=gts_id, ok=True)
+        except Exception as e:
+            return GtsValidationResult(id=gts_id, ok=False, error=str(e))
+
     def schema_graph(self, gts_id: str) -> GtsSchemaGraphResult:
         graph = self.store.build_schema_graph(gts_id)
         return GtsSchemaGraphResult(graph=graph)
@@ -372,6 +441,35 @@ def extract_id(self, content: Dict[str, Any]) -> GtsExtractIdResult:
             is_schema=entity.is_schema,
         )
 
+    def get_entity(self, gts_id: str) -> GtsGetEntityResult:
+        """Get a single entity by its GTS ID.
+
+        Args:
+            gts_id: The GTS ID of the entity to retrieve
+
+        Returns:
+            GtsGetEntityResult with entity details or error
+        """
+        try:
+            entity = self.store.get(gts_id)
+            if not entity:
+                return GtsGetEntityResult(
+                    ok=False,
+                    error=f"Entity '{gts_id}' not found"
+                )
+            return GtsGetEntityResult(
+                ok=True,
+                id=entity.gts_id.id if entity.gts_id else gts_id,
+                schema_id=entity.schemaId,
+                is_schema=entity.is_schema,
+                content=entity.content
+            )
+        except Exception as e:
+            return GtsGetEntityResult(
+                ok=False,
+                error=str(e)
+            )
+
     def get_entities(self, limit: int = 100) -> GtsEntitiesListResult:
         """Get all entities in the registry.
 
@@ -391,7 +489,9 @@ def get_entities(self, limit: int = 100) -> GtsEntitiesListResult:
             )
             for entity_id, entity in all_entities[:limit]
         ]
-        return GtsEntitiesListResult(entities=entities, count=len(entities), total=total)
+        return GtsEntitiesListResult(
+            entities=entities, count=len(entities), total=total
+        )
 
     def list(self, limit: int = 100) -> GtsEntitiesListResult:
         """Alias for get_entities. List all discovered entities.

gts/src/gts/server.py

@@ -178,6 +178,13 @@ def _register_routes(self) -> None:
             summary="Get all entities in the registry",
             response_class=JSONResponse,
         )
+        app.add_api_route(
+            "/entities/{gts_id:path}",
+            self.get_entity,
+            methods=["GET"],
+            summary="Get a specific entity by GTS ID",
+            response_class=JSONResponse,
+        )
         app.add_api_route(
             "/entities",
             self.add_entity,
@@ -287,8 +294,14 @@ def _register_routes(self) -> None:
         )
 
     # Handlers as methods (no free functions)
-    async def add_entity(self, body: Dict[str, Any] = Body(...)) -> JSONResponse:
-        return JSONResponse(self.ops.add_entity(body).to_dict())
+    async def add_entity(
+        self,
+        body: Dict[str, Any] = Body(...),
+        validate: bool = Query(False)
+    ) -> JSONResponse:
+        return JSONResponse(
+            self.ops.add_entity(body, validate=validate).to_dict()
+        )
 
     async def add_entities(self, body: List[Dict[str, Any]] = Body(...)) -> JSONResponse:
         return JSONResponse(self.ops.add_entities(body).to_dict())
@@ -339,5 +352,10 @@ async def query(self, expr: str = Query(...), limit: int = Query(100, ge=1, le=1
     async def attr(self, gts_with_path: str = Query(...)) -> Dict[str, Any]:
         return self.ops.attr(gts_with_path).to_dict()
 
-    async def get_entities(self, limit: int = Query(100, ge=1, le=1000)) -> Dict[str, Any]:
+    async def get_entity(self, gts_id: str) -> Dict[str, Any]:
+        return self.ops.get_entity(gts_id).to_dict()
+
+    async def get_entities(
+        self, limit: int = Query(100, ge=1, le=1000)
+    ) -> Dict[str, Any]:
         return self.ops.get_entities(limit=limit).to_dict()