GTS TypeScript Implementation

A complete TypeScript implementation of the Global Type System (GTS)

Overview

GTS Global Type System is a simple, human-readable, globally unique identifier and referencing system for data type definitions (e.g., JSON Schemas) and data instances (e.g., JSON objects). This TypeScript implementation provides type-safe operations for working with GTS identifiers.

Roadmap

Featureset:

• OP#1 - ID Validation: Verify identifier syntax using regex patterns
• OP#2 - ID Extraction: Fetch identifiers from JSON objects or JSON Schema documents
• OP#3 - ID Parsing: Decompose identifiers into constituent parts (vendor, package, namespace, type, version, etc.)
• OP#4 - ID Pattern Matching: Match identifiers against patterns containing wildcards
• OP#5 - ID to UUID Mapping: Generate deterministic UUIDs from GTS identifiers
• OP#6 - Schema Validation: Validate object instances against their corresponding schemas
• OP#7 - Relationship Resolution: Load all schemas and instances, resolve inter-dependencies, and detect broken references
• 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
• OP#9 - Version Casting: Transform instances between compatible MINOR versions
• OP#10 - Query Execution: Filter identifier collections using the GTS query language
• OP#11 - Attribute Access: Retrieve property values and metadata using the attribute selector (@)

Other GTS spec Reference Implementation recommended features support:

• In-memory entities registry - simple GTS entities registry with optional GTS references validation on entity registration
• CLI - command-line interface for all GTS operations
• Web server - a non-production web-server with REST API for the operations processing and testing
• x-gts-ref - 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 files (*.tsp) support
• UUID for instances - to support UUID as ID in JSON instances

Usage

Basic Operations

import{isValidGtsID,validateGtsID,parseGtsID,matchIDPattern,idToUUID}from'@globaltypesystem/gts-ts';// OP#1 - ID Validationif(isValidGtsID('gts.vendor.pkg.ns.type.v1~')){console.log('Valid GTS ID');}constresult=validateGtsID('gts.vendor.pkg.ns.type.v1~');if(result.valid){console.log(`Valid: ${result.id}`);}else{console.log(`Invalid: ${result.error}`);}// OP#2 - ID Extractionimport{extractID}from'@globaltypesystem/gts-ts';constcontent={gtsId: 'gts.vendor.pkg.ns.type.v1.0',name: 'My Entity'};constextracted=extractID(content);console.log(`ID: ${extracted.id}`);console.log(`Schema ID: ${extracted.schemaId}`);// OP#3 - ID Parsingconstparsed=parseGtsID('gts.vendor.pkg.ns.type.v1~');if(parsed.ok){for(constsegofparsed.segments){console.log(`Vendor: ${seg.vendor}, Package: ${seg.package}, Type: ${seg.type}, Version: v${seg.verMajor}`);}}// OP#4 - Pattern MatchingconstmatchResult=matchIDPattern('gts.vendor.pkg.ns.type.v1.0','gts.vendor.pkg.*');if(matchResult.match){console.log('Pattern matched!');}// OP#5 - UUID GenerationconstuuidResult=idToUUID('gts.vendor.pkg.ns.type.v1~');console.log(`UUID: ${uuidResult.uuid}`);

Using the GTS Store

import{GTS}from'@globaltypesystem/gts-ts';// Create a new storeconstgts=newGTS();// Register an entityconstentity={gtsId: 'gts.vendor.pkg.ns.type.v1.0',name: 'My Entity'};gts.register(entity);// OP#6 - Validate an instanceconstvalidation=gts.validateInstance('gts.vendor.pkg.ns.type.v1.0');if(validation.ok){console.log('Instance is valid');}// OP#7 - Resolve relationshipsconstrelationships=gts.resolveRelationships('gts.vendor.pkg.ns.type.v1.0');console.log(`Relationships: ${relationships.relationships}`);console.log(`Broken references: ${relationships.brokenReferences}`);// OP#8 - Check compatibilityconstcompatResult=gts.checkCompatibility('gts.vendor.pkg.ns.type.v1~','gts.vendor.pkg.ns.type.v2~','backward');if(compatResult.compatible){console.log('Schemas are compatible');}// OP#9 - Cast instance to different versionconstcastResult=gts.castInstance('gts.vendor.pkg.ns.type.v1.0','gts.vendor.pkg.ns.type.v2~');if(castResult.ok){console.log('Instance casted successfully');}// OP#10 - Query entitiesconstqueryResult=gts.query('gts.vendor.pkg.*',100);console.log(`Found ${queryResult.count} entities`);// OP#11 - Attribute accessconstattr=gts.getAttribute('gts.vendor.pkg.ns.type.v1.0@name');if(attr.resolved){console.log(`Attribute value: ${attr.value}`);}

Advanced Query Language

The query language supports complex expressions with AND, OR, and NOT operators:

// Simple pattern matchinggts.query('gts.vendor.*');// Complex queries with logical operatorsgts.query('gts.vendor.* OR gts.other.*');gts.query('gts.vendor.* AND NOT gts.vendor.test.*');gts.query('(gts.vendor.* OR gts.other.*) AND gts.*.*.ns.*');

CLI Usage

The package includes a CLI tool for GTS operations:

# Install globally
npm install -g @globaltypesystem/gts-ts
# Or use locally with npx
npx gts
# Basic operations
gts validate-id -i gts.vendor.pkg.ns.type.v1~
gts parse-id -i gts.vendor.pkg.ns.type.v1.0
gts match-id -p "gts.vendor.pkg.*" -c gts.vendor.pkg.ns.type.v1.0
gts uuid -i gts.vendor.pkg.ns.type.v1~
# Operations with loaded entities
gts --path ./examples validate -i gts.vendor.pkg.ns.type.v1.0
gts --path ./examples relationships -i gts.vendor.pkg.ns.type.v1~
gts --path ./examples compatibility -o gts.vendor.pkg.ns.type.v1~ -n gts.vendor.pkg.ns.type.v2~
gts --path ./examples cast -f gts.vendor.pkg.ns.type.v1.0 -t gts.vendor.pkg.ns.type.v2~
gts --path ./examples query -e "gts.vendor.pkg.*" -l 10
gts --path ./examples attr -p gts.vendor.pkg.ns.type.v1.0@name
gts --path ./examples list -l 100

Web Server

The package includes a non-production web server with REST API for testing and development:

Building the Server

# install dependencies
npm ci
# build the server
npm run build

Starting the Server

# Using npm scripts
npm run server
# Using the CLI
gts server --host 127.0.0.1 --port 8000
# With preloaded entities
gts --path ./examples server --port 8001
# Using the dedicated server command
npx gts-server --host 127.0.0.1 --port 8000 --verbose 2

API Endpoints

Entity Management

• GET /entities - List all entities
• GET /entities/:id - Get specific entity
• POST /entities - Add new entity
• POST /entities/bulk - Add multiple entities
• POST /schemas - Add new schema

GTS Operations

• GET /validate-id?id=<gts_id> - Validate GTS ID (OP#1)
• POST /extract-id - Extract GTS ID from JSON (OP#2)
• GET /parse-id?id=<gts_id> - Parse GTS ID (OP#3)
• GET /match-id-pattern?pattern=<pattern>&candidate=<id> - Match pattern (OP#4)
• GET /uuid?id=<gts_id> - Generate UUID (OP#5)
• POST /validate-instance - Validate instance (OP#6)
• GET /resolve-relationships?id=<gts_id> - Resolve relationships (OP#7)
• GET /compatibility?old=<id>&new=<id>&mode=<mode> - Check compatibility (OP#8)
• POST /cast - Cast instance (OP#9)
• GET /query?expr=<expression>&limit=<limit> - Query entities (OP#10)
• GET /attr?path=<path> - Get attribute value (OP#11)

Other

• GET /health - Health check
• GET /openapi - OpenAPI specification

Example Usage

# Health check
curl http://127.0.0.1:8000/health
# Validate a GTS ID
curl "http://127.0.0.1:8000/validate-id?id=gts.vendor.pkg.ns.type.v1~"# Add a schema
curl -X POST http://127.0.0.1:8000/schemas \
-H "Content-Type: application/json" \
-d '{ "$$id": "gts.test.example.ns.person.v1~", "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "number" } }, "required": ["name"] }'# Query entities
curl "http://127.0.0.1:8000/query?expr=gts.test.*&limit=10"

Development

# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test# Run linting
npm run lint
# Type checking
npm run typecheck
# Format code
npm run format
# Start development server
npm run server:dev

License

Apache License 2.0