Skip to content
BranchesTags

Repository files navigation

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 - Instance 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 (@)
  • OP#12 - Schema Validation: Validate schema against its precedent schema

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)
  • POST /validate-schema - Validate schema against parent schema (OP#12)
  • POST /validate-entity - Validate entity (schema or instance) (OP#12)

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

About

TypeScript implementation of the GTS library

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages