Skip to content

README.md

Latest commit

 

History

History
209 lines (149 loc) · 5.26 KB

README.md

File metadata and controls

209 lines (149 loc) · 5.26 KB

GTS Python Library

A minimal, idiomatic Python library for working with GTS (Global Type System) identifiers and type definitions.

File Format Support

GTS Python supports multiple file formats for schemas and instances:

JSON (Native)

Standard JSON format with .json, .jsonc, and .gts extensions.

YAML

Full YAML support with .yaml and .yml extensions. YAML files are automatically parsed and treated identically to JSON.

from gts import GtsFileReader

# Reads both JSON and YAML files
reader = GtsFileReader("path/to/schemas/")
for entity in reader:
    print(f"{entity.gts_id.id}: {entity.file.name}")

TypeSpec

TypeSpec (.tsp) schemas must be pre-compiled to JSON Schema before use with gts-python.

Setup:

# Install TypeSpec compiler
npm install -g @typespec/compiler @typespec/json-schema

# Compile TypeSpec to JSON Schema
tsp compile --emit @typespec/json-schema your-schemas/

Usage:

from gts import GtsFileReader

# Point to the generated JSON Schema output directory
reader = GtsFileReader("tsp-output/@typespec/json-schema/")
entities = list(reader)

See gts-spec TypeSpec examples for sample TypeSpec definitions.

Featureset

GTS specifiaciton reference implementations status:

  • OP#1 - ID Validation: Verify identifier syntax using regex patterns
from gts import GtsID

is_valid = GtsID.is_valid("gts.x.core.events.event.v1~")
print(is_valid)  # True or False
  • OP#2 - ID Extraction: Fetch identifiers from JSON objects or JSON Schema documents
import json
from gts import GtsEntity, DEFAULT_GTS_CONFIG

content = json.load(open("path/to/file.json"))
entity = GtsEntity(content=content, cfg=DEFAULT_GTS_CONFIG)
if entity.gts_id:
    print(entity.gts_id.id)
  • OP#3 - ID Parsing: Decompose identifiers into constituent parts (vendor, package, namespace, type, version, etc.)
from gts import GtsID

gts = GtsID("gts.x.core.events.event.v1~")
print(gts.gts_id_segments)
  • OP#4 - ID Pattern Matching: Match identifiers against patterns containing wildcards
from gts import GtsID, GtsWildcard

gts = GtsID("gts.x.core.events.event.v1.0~")
pattern = GtsWildcard("gts.x.core.events.event.v1~*")
gts.wildcard_match(pattern)  # True - v1~* matches any v1.x~
  • OP#5 - ID to UUID Mapping: Generate deterministic UUIDs from GTS identifiers
from gts import GtsID

gts = GtsID("gts.x.core.events.event.v1~")
uuid = gts.to_uuid()
print(uuid)
  • OP#6 - Schema Validation: Validate object instances against their corresponding schemas
from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
try:
    store.validate_instance(gts_id="gts.x.core.events.event.v1.0~instance.v1")
    print("Validation successful")
except Exception as e:
    print(f"Validation failed: {e}")
  • OP#7 - Relationship Resolution: Load all schemas and instances, resolve inter-dependencies, and detect broken references
from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
entity = store.get("gts.x.core.events.event.v1~")
# or build a dependency graph for a specific GTS ID
graph = store.build_schema_graph(gts_id="gts.x.core.events.event.v1~")

  • OP#8 - Compatibility Checking: Verify that schemas with different MINOR versions are compatible

  • OP#8.1 - Backward compatibility checking

  • OP#8.2 - Forward compatibility checking

  • OP#8.3 - Full compatibility checking

from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
compatible = store.is_minor_compatible(
    "gts.x.core.events.event.v1.0~",
    "gts.x.core.events.event.v1.1~"
)
print(compatible.is_backward_compatible)
print(compatible.is_forward_compatible)
print(compatible.is_fully_compatible)
  • OP#9 - Version Casting: Transform instances between compatible MINOR versions
from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
result = store.cast(
    from_id="gts.x.core.events.event.v1.0~instance.v1",
    target_schema_id="gts.x.core.events.event.v1.1~"
)
  • OP#10 - Query Execution: Filter identifier collections using the GTS query language
from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
result = store.query("gts.x.core.events.event.v1~[status=active, user=123]")
print(f"Found {result.count} entities")
for entity in result.results:
    print(entity)
  • OP#11 - Attribute Access: Retrieve property values and metadata using the attribute selector (@)
from gts import GtsStore, GtsFileReader

reader = GtsFileReader(path="path/to/gts/files")
store = GtsStore(reader=reader)
entity = store.get("gts.x.core.events.event.v1~")
if entity:
    res = entity.resolve_path("gtsId")
    if res.resolved:
        print(res.value)
    else:
        print(res.error)