gts-spec v0.14 compliance

Makefile

@@ -26,7 +26,7 @@ $(error PYTHON must be set for local package targets (examples: venv: PYTHON=.ve
 endif
 endif
 
-.PHONY: help py-env install build install-local uninstall-local clean dev-fmt all check fmt lint clippy mypy test security update-spec e2e coverage
+.PHONY: help py-env install build install-local uninstall-local clean dev-fmt all check fmt lint clippy mypy test security update-spec e2e coverage gts-server
 
 # Default target - show help
 .DEFAULT_GOAL := help
@@ -100,6 +100,11 @@ lint: py-env
 clippy: py-env
 	$(PYTHON) -m ruff check --fix gts/src
 
+# Format code and apply auto-fixable lint corrections
+fix: py-env
+	$(PYTHON) -m ruff format gts/src
+	$(PYTHON) -m ruff check --fix gts/src
+
 # Run type checker
 mypy: py-env
 	$(PYTHON) -m mypy gts/src/gts --ignore-missing-imports
@@ -115,6 +120,11 @@ coverage: install
 	$(PYTHON) -m pip install 'pytest-cov>=5,<7'
 	$(PYTHON) -m pytest tests/ --cov=gts --cov-report=xml --cov-report=term
 
+PORT ?= 8000
+
+gts-server: install
+	$(PYTHON) -m gts server --host 127.0.0.1 --port $(PORT)
+
 # Run end-to-end tests against gts-spec
 e2e: install
 	@echo "Starting server in background..."

README.md

@@ -4,7 +4,7 @@
 
 A minimal, idiomatic Python library for working with **GTS** ([Global Type System](https://github.com/gts-spec/gts-spec)) identifiers and JSON/JSON Schema artifacts.
 
-Current supported GTS spec version: `0.13.4`
+Current supported GTS spec version: `0.14.0`
 
 ## Roadmap
 

gts/README.md

@@ -2,7 +2,7 @@
 
 Python helpers and a reference HTTP service for the [Global Type System (GTS)](https://github.com/globaltypesystem/gts-spec). The package supports GTS identifier parsing, JSON Schema-backed validation, schema compatibility and derivation checks, traits, casting, queries, file loading, a CLI, and a FastAPI application.
 
-The package targets GTS specification v0.13.4 and requires Python 3.9 or later.
+The package targets GTS specification v0.14.0 and requires Python 3.9 or later.
 
 ## Installation
 

gts/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "GTS Server",
-    "version": "0.13.4"
+    "version": "0.14.0"
   },
   "paths": {
     "/entities": {

gts/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gts"
-version = "0.13.4"
+version = "0.14.0"
 description = "Global Type System (GTS) helpers: identifiers, parsing, validation, and operations"
 readme = "README.md"
 authors = [{ name = "GTS Community" }]

gts/src/gts/__init__.py

@@ -14,6 +14,7 @@
     GtsIdSegment,
     GtsWildcard,
 )
+from .gts_ref_validation import GtsRefValidationMode
 from .path_resolver import GtsPathResolver
 from .store import (
     GtsReader,
@@ -30,6 +31,7 @@
     "GtsIdSegment",
     "GtsPathResolver",
     "GtsReader",
+    "GtsRefValidationMode",
     "GtsStore",
     "GtsWildcard",
     "JsonEntity",

gts/src/gts/_server.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+# ruff: noqa: B008
 import logging
 import sys
 import time
@@ -10,9 +11,13 @@
 from pydantic import BaseModel, model_validator
 from starlette.middleware.base import BaseHTTPMiddleware
 
+from .gts_ref_validation import GtsRefValidationMode
 from .ops import GtsOps
 
 logger = logging.getLogger(__name__)
+GTS_REF_VALIDATION_QUERY = Query(
+    GtsRefValidationMode.ANY_VALID, alias="gts-ref-validation"
+)
 
 
 # ANSI color codes
@@ -188,7 +193,7 @@ def __init__(
         self.host = host
         self.port = port
         self.base_url = f"http://{self.host}:{self.port}"
-        self.app = FastAPI(title="GTS Server", version="0.13.4")
+        self.app = FastAPI(title="GTS Server", version="0.14.0")
         self.app.add_middleware(
             _RequestLoggingMiddleware,
             verbose=self.ops.verbose,
@@ -343,16 +348,22 @@ def _register_routes(self) -> None:
     # Handlers as methods (no free functions)
     async def add_entity(
         self,
-        body: dict[str, Any] = Body(...),  # noqa: B008 - FastAPI dependency pattern
+        body: dict[str, Any] = Body(...),
         validate: bool = Query(False),
+        validation: bool = Query(False),
+        gts_ref_validation: GtsRefValidationMode = GTS_REF_VALIDATION_QUERY,
     ) -> JSONResponse:
-        result = self.ops.add_entity(body, validate=validate)
+        result = self.ops.add_entity(
+            body,
+            validate=validate is True or validation is True,
+            gts_ref_validation=gts_ref_validation,
+        )
         status_code = 200 if result.ok else 409 if result.conflict else 422
         return JSONResponse(result.to_dict(), status_code=status_code)
 
     async def add_entities(
         self,
-        body: list[dict[str, Any]] = Body(...),  # noqa: B008 - FastAPI dependency pattern
+        body: list[dict[str, Any]] = Body(...),
     ) -> JSONResponse:
         return JSONResponse(self.ops.add_entities(body).to_dict())
 
@@ -367,7 +378,7 @@ async def validate_id(self, id: str = Query(..., alias="gts_id")) -> dict[str, A
 
     async def extract_id(
         self,
-        body: dict[str, Any] = Body(...),  # noqa: B008 - FastAPI dependency pattern
+        body: dict[str, Any] = Body(...),
     ) -> dict[str, Any]:
         return self.ops.extract_id(body).to_dict()
 
@@ -384,29 +395,41 @@ async def match_id_pattern(
     async def id_to_uuid(self, id: str = Query(..., alias="gts_id")) -> dict[str, Any]:
         return self.ops.uuid(id).to_dict()
 
-    async def validate_instance(self, body: ValidateInstanceRequest) -> dict[str, Any]:
-        return self.ops.validate_instance(body.instance_id).to_dict()
+    async def validate_instance(
+        self,
+        body: ValidateInstanceRequest,
+        gts_ref_validation: GtsRefValidationMode = GTS_REF_VALIDATION_QUERY,
+    ) -> dict[str, Any]:
+        return self.ops.validate_instance(
+            body.instance_id, gts_ref_validation
+        ).to_dict()
 
     async def validate_json(
         self,
-        body: dict[str, Any] = Body(...),  # noqa: B008 - FastAPI dependency pattern
+        body: dict[str, Any] = Body(...),
     ) -> dict[str, Any]:
         return self.ops.validate_json(body).to_dict()
 
     async def validate_json_as_type(
         self,
         gts_type: str,
-        body: dict[str, Any] = Body(...),  # noqa: B008 - FastAPI dependency pattern
+        body: dict[str, Any] = Body(...),
     ) -> dict[str, Any]:
         return self.ops.validate_json(body, explicit_type_id=gts_type).to_dict()
 
     async def validate_type_schema(
-        self, body: ValidateTypeSchemaRequest
+        self,
+        body: ValidateTypeSchemaRequest,
+        gts_ref_validation: GtsRefValidationMode = GTS_REF_VALIDATION_QUERY,
     ) -> dict[str, Any]:
-        return self.ops.validate_schema(body.type_id).to_dict()
+        return self.ops.validate_schema(body.type_id, gts_ref_validation).to_dict()
 
-    async def validate_entity(self, body: ValidateEntityRequest) -> dict[str, Any]:
-        return self.ops.validate_entity(body.resolved_id).to_dict()
+    async def validate_entity(
+        self,
+        body: ValidateEntityRequest,
+        gts_ref_validation: GtsRefValidationMode = GTS_REF_VALIDATION_QUERY,
+    ) -> dict[str, Any]:
+        return self.ops.validate_entity(body.resolved_id, gts_ref_validation).to_dict()
 
     async def schema_graph(
         self, id: str = Query(..., alias="gts_id")

gts/src/gts/gts_ref_validation.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class GtsRefValidationMode(str, Enum):
+    NONE = "none"
+    ANY_PRESENT = "any-present"
+    ANY_VALID = "any-valid"

gts/src/gts/ops.py

@@ -10,13 +10,23 @@
 from .entities import DEFAULT_GTS_CONFIG, GtsConfig, GtsEntity
 from .files_reader import GtsFileReader
 from .gts import GtsID, GtsWildcard
+from .gts_ref_validation import GtsRefValidationMode
 from .path_resolver import GtsPathResolver
 from .schema_cast import GtsEntityCastResult
 from .store import GtsStore, GtsStoreQueryResult
 
 # Interface helpers
 
 
+def _normalize_gts_ref_validation(value: Any) -> GtsRefValidationMode:
+    if isinstance(value, GtsRefValidationMode):
+        return value
+    try:
+        return GtsRefValidationMode(value)
+    except (TypeError, ValueError):
+        return GtsRefValidationMode.ANY_VALID
+
+
 @dataclass
 class GtsIdValidationResult:
     """Result of validating a GTS ID format."""
@@ -384,8 +394,12 @@ 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,
+        gts_ref_validation: GtsRefValidationMode = GtsRefValidationMode.ANY_VALID,
     ) -> GtsAddEntityResult:
+        gts_ref_validation = _normalize_gts_ref_validation(gts_ref_validation)
         entity = GtsEntity(content=content, cfg=self.cfg)
 
         # For instances (non-schemas), require an id field from entity_id_fields
@@ -429,9 +443,11 @@ def add_entity(
             if entity.is_schema:
                 self.store.validate_schema_basic(entity.gts_id.id)
                 if validate:
-                    self.store.validate_schema(entity.gts_id.id)
+                    self.store.validate_schema(entity.gts_id.id, gts_ref_validation)
             elif validate:
-                self.store.validate_instance(entity.raw_id or entity.gts_id.id)
+                self.store.validate_instance(
+                    entity.raw_id or entity.gts_id.id, gts_ref_validation
+                )
         except Exception as e:  # noqa: BLE001 - converted to a result object at API boundary
             self.store.unregister(store_key)
             if previous:
@@ -652,34 +668,52 @@ def validate_json(
             is_type_schema=entity.is_schema,
         )
 
-    def validate_instance(self, gts_id: str) -> GtsValidationResult:
+    def validate_instance(
+        self,
+        gts_id: str,
+        gts_ref_validation: GtsRefValidationMode = GtsRefValidationMode.ANY_VALID,
+    ) -> GtsValidationResult:
+        gts_ref_validation = _normalize_gts_ref_validation(gts_ref_validation)
         try:
-            self.store.validate_instance(gts_id)
+            self.store.validate_instance(gts_id, gts_ref_validation)
             return GtsValidationResult(id=gts_id, ok=True)
         except Exception as e:  # noqa: BLE001 - converted to a result object at API boundary
             return GtsValidationResult(id=gts_id, ok=False, error=str(e))
 
-    def validate_schema(self, gts_id: str) -> GtsValidationResult:
+    def validate_schema(
+        self,
+        gts_id: str,
+        gts_ref_validation: GtsRefValidationMode = GtsRefValidationMode.ANY_VALID,
+    ) -> GtsValidationResult:
+        gts_ref_validation = _normalize_gts_ref_validation(gts_ref_validation)
         try:
-            self.store.validate_schema(gts_id)
+            self.store.validate_schema(gts_id, gts_ref_validation)
             return GtsValidationResult(id=gts_id, ok=True)
         except Exception as e:  # noqa: BLE001 - converted to a result object at API boundary
             return GtsValidationResult(id=gts_id, ok=False, error=str(e))
 
-    def validate_entity(self, gts_id: str) -> GtsEntityValidationResult:
-        try:
-            parsed = GtsID(gts_id)
-        except Exception as e:  # noqa: BLE001 - converted to a result object at API boundary
-            return GtsEntityValidationResult(
-                id=gts_id, ok=False, entity_type="", error=str(e)
-            )
+    def validate_entity(
+        self,
+        gts_id: str,
+        gts_ref_validation: GtsRefValidationMode = GtsRefValidationMode.ANY_VALID,
+    ) -> GtsEntityValidationResult:
+        gts_ref_validation = _normalize_gts_ref_validation(gts_ref_validation)
+        entity = self.store.get(gts_id)
+        if entity:
+            entity_type = "schema" if entity.is_schema else "instance"
+        else:
+            try:
+                parsed = GtsID(gts_id)
+                entity_type = "schema" if parsed.is_type else "instance"
+            except Exception as e:  # noqa: BLE001 - converted at API boundary
+                return GtsEntityValidationResult(
+                    id=gts_id, ok=False, entity_type="", error=str(e)
+                )
 
-        if parsed.is_type:
-            entity_type = "schema"
-            result = self.validate_schema(gts_id)
+        if entity_type == "schema":
+            result = self.validate_schema(gts_id, gts_ref_validation)
         else:
-            entity_type = "instance"
-            result = self.validate_instance(gts_id)
+            result = self.validate_instance(gts_id, gts_ref_validation)
 
         return GtsEntityValidationResult(
             id=result.id, ok=result.ok, entity_type=entity_type, error=result.error