gts

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 27, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// GtsPrefix is the required prefix for all GTS identifiers
	GtsPrefix = "gts."
	// GtsURIPrefix is the URI-compatible prefix for GTS identifiers in JSON Schema $id field
	// (e.g., "gts://gts.x.y.z..."). This is ONLY used for JSON Schema serialization/deserialization,
	// not for GTS ID parsing.
	GtsURIPrefix = "gts://"
	// MaxIDLength is the maximum allowed length for a GTS identifier
	MaxIDLength = 1024
)

Variables

View Source
var (
	// ExcludeList contains directory names to exclude during file scanning
	ExcludeList = []string{"node_modules", "dist", "build"}
)
View Source
var (
	// GtsNamespace is the UUID namespace for GTS identifiers
	// Generated as uuid5(NAMESPACE_URL, "gts")
	GtsNamespace = uuid.NewSHA1(uuid.NameSpaceURL, []byte("gts"))
)

Functions

func IsValidGtsID

func IsValidGtsID(s string) bool

IsValidGtsID checks if a string is a valid GTS identifier

Types

type AttributeResult

type AttributeResult struct {
	GtsID           string   `json:"gts_id"`
	Path            string   `json:"path"`
	Value           any      `json:"value,omitempty"`
	Resolved        bool     `json:"resolved"`
	Error           string   `json:"error,omitempty"`
	AvailableFields []string `json:"available_fields,omitempty"`
}

AttributeResult represents the result of attribute path resolution

type CastResult

type CastResult struct {
	*CompatibilityResult
	CastedEntity map[string]any `json:"casted_entity,omitempty"`
}

CastResult represents the result of casting an instance to a new schema version It extends CompatibilityResult with the casted entity

type CompatibilityResult

type CompatibilityResult struct {
	FromID                 string              `json:"from"`
	ToID                   string              `json:"to"`
	OldID                  string              `json:"old"`
	NewID                  string              `json:"new"`
	Direction              string              `json:"direction"`
	AddedProperties        []string            `json:"added_properties"`
	RemovedProperties      []string            `json:"removed_properties"`
	ChangedProperties      []map[string]string `json:"changed_properties"`
	IsFullyCompatible      bool                `json:"is_fully_compatible"`
	IsBackwardCompatible   bool                `json:"is_backward_compatible"`
	IsForwardCompatible    bool                `json:"is_forward_compatible"`
	IncompatibilityReasons []string            `json:"incompatibility_reasons"`
	BackwardErrors         []string            `json:"backward_errors"`
	ForwardErrors          []string            `json:"forward_errors"`
	Error                  string              `json:"error,omitempty"`
}

CompatibilityResult represents the result of schema compatibility checking

type EntityInfo

type EntityInfo struct {
	ID       string `json:"id"`
	SchemaID string `json:"schema_id"`
	IsSchema bool   `json:"is_schema"`
}

EntityInfo represents basic information about an entity

type ExtractIDResult

type ExtractIDResult struct {
	ID                    string  `json:"id"`
	SchemaID              *string `json:"schema_id"`
	SelectedEntityField   *string `json:"selected_entity_field"`
	SelectedSchemaIDField *string `json:"selected_schema_id_field"`
	IsSchema              bool    `json:"is_schema"`
}

ExtractIDResult holds the result of extracting ID information from JSON content

func ExtractGtsID

func ExtractGtsID(content map[string]any, cfg *GtsConfig) *ExtractIDResult

ExtractGtsID extracts GTS ID from JSON content

func ExtractID

func ExtractID(content map[string]any, cfg *GtsConfig) *ExtractIDResult

ExtractID extracts GTS ID information from JSON content

type GtsConfig

type GtsConfig struct {
	EntityIDFields []string
	SchemaIDFields []string
}

GtsConfig holds configuration for extracting GTS IDs from JSON content

func DefaultGtsConfig

func DefaultGtsConfig() *GtsConfig

DefaultGtsConfig returns the default configuration for ID extraction

type GtsFileReader

type GtsFileReader struct {
	// contains filtered or unexported fields
}

GtsFileReader reads JSON entities from files and directories

func NewGtsFileReader

func NewGtsFileReader(paths []string, cfg *GtsConfig) *GtsFileReader

NewGtsFileReader creates a new file reader with the given paths

func NewGtsFileReaderFromPath

func NewGtsFileReaderFromPath(path string, cfg *GtsConfig) *GtsFileReader

NewGtsFileReaderFromPath creates a new file reader from a single path

func (*GtsFileReader) Next

func (r *GtsFileReader) Next() *JsonEntity

Next returns the next JsonEntity or nil when exhausted

func (*GtsFileReader) ReadByID

func (r *GtsFileReader) ReadByID(entityID string) *JsonEntity

ReadByID reads a JsonEntity by its ID For FileReader, this returns nil as we don't support random access by ID

func (*GtsFileReader) Reset

func (r *GtsFileReader) Reset()

Reset resets the iterator to start from the beginning

type GtsID

type GtsID struct {
	ID       string
	Segments []*GtsIDSegment
}

GtsID represents a validated GTS identifier

func NewGtsID

func NewGtsID(id string) (*GtsID, error)

NewGtsID creates and validates a new GTS identifier

func (*GtsID) IsType

func (g *GtsID) IsType() bool

IsType returns true if this identifier represents a type (ends with ~)

func (*GtsID) IsWildcard added in v0.7.0

func (g *GtsID) IsWildcard() bool

IsWildcard returns true if this identifier contains wildcard patterns

func (*GtsID) ToUUID

func (g *GtsID) ToUUID() uuid.UUID

ToUUID generates a deterministic UUID (v5) from the GTS identifier The UUID is generated using uuid5(GTS_NAMESPACE, gts_id)

type GtsIDSegment

type GtsIDSegment struct {
	Num        int
	Offset     int
	Segment    string
	Vendor     string
	Package    string
	Namespace  string
	Type       string
	VerMajor   int
	VerMinor   *int
	IsType     bool
	IsWildcard bool
}

GtsIDSegment represents a parsed segment of a GTS identifier

type GtsReader

type GtsReader interface {
	// Next returns the next JsonEntity or nil when exhausted
	Next() *JsonEntity

	// ReadByID reads a JsonEntity by its ID
	// Returns nil if the entity is not found
	ReadByID(entityID string) *JsonEntity

	// Reset resets the iterator to start from the beginning
	Reset()
}

GtsReader is an interface for reading JSON entities from various sources

type GtsReference

type GtsReference struct {
	ID         string
	SourcePath string
}

GtsReference represents a GTS ID reference found in JSON content

type GtsStore

type GtsStore struct {
	// contains filtered or unexported fields
}

GtsStore manages a collection of JSON entities and schemas with optional GTS reference validation

func NewGtsStore

func NewGtsStore(reader GtsReader) *GtsStore

NewGtsStore creates a new GtsStore, optionally populating it from a reader

func NewGtsStoreWithConfig

func NewGtsStoreWithConfig(reader GtsReader, config *RegistryConfig) *GtsStore

NewGtsStoreWithConfig creates a new GtsStore with custom configuration

func (*GtsStore) BuildSchemaGraph

func (s *GtsStore) BuildSchemaGraph(gtsID string) *SchemaGraphNode

BuildSchemaGraph recursively builds a relationship graph for a GTS entity This matches Python's build_schema_graph method in store.py

func (*GtsStore) Cast

func (s *GtsStore) Cast(instanceID, toSchemaID string) (*CastResult, error)

Cast transforms an instance to conform to a target schema version see gts-python store.py cast method

func (*GtsStore) CheckCompatibility

func (s *GtsStore) CheckCompatibility(oldSchemaID, newSchemaID string) *CompatibilityResult

CheckCompatibility checks compatibility between two schemas see gts-python store.py is_minor_compatible method

func (*GtsStore) Count

func (s *GtsStore) Count() int

Count returns the number of entities in the store

func (*GtsStore) Get

func (s *GtsStore) Get(entityID string) *JsonEntity

Get retrieves a JsonEntity by its ID If not found in cache, attempts to fetch from reader

func (*GtsStore) GetAttribute

func (s *GtsStore) GetAttribute(gtsWithPath string) *AttributeResult

GetAttribute retrieves an attribute value from an entity using a path selector Format: "gts_id@path.to.field" or "gts_id@array[0].field" see gts-python ops.py attr method

func (*GtsStore) GetSchemaContent

func (s *GtsStore) GetSchemaContent(typeID string) (map[string]any, error)

GetSchemaContent retrieves schema content as a map (legacy method)

func (*GtsStore) Items

func (s *GtsStore) Items() map[string]*JsonEntity

Items returns all entity ID and entity pairs

func (*GtsStore) List

func (s *GtsStore) List(limit int) *ListResult

List returns a list of entities up to the specified limit

func (*GtsStore) Query

func (s *GtsStore) Query(expr string, limit int) *QueryResult

Query filters entities by a GTS query expression Supports: - Exact match: "gts.x.core.events.event.v1~" - Wildcard match: "gts.x.core.events.*" - With filters: "gts.x.core.events.event.v1~[status=active]" - Wildcard with filters: "gts.x.core.*[status=active]" - Wildcard filter values: "gts.x.core.*[status=active, category=*]" see gts-python store.py query method

func (*GtsStore) Register

func (s *GtsStore) Register(entity *JsonEntity) error

Register adds a JsonEntity to the store with optional GTS reference validation

func (*GtsStore) RegisterSchema

func (s *GtsStore) RegisterSchema(typeID string, schema map[string]any) error

RegisterSchema registers a schema with the given type ID This is a legacy method for backward compatibility

func (*GtsStore) ValidateInstance

func (s *GtsStore) ValidateInstance(gtsID string) *ValidationResult

ValidateInstance validates an object instance against its schema Returns ValidationResult with ok=true if validation succeeds

func (*GtsStore) ValidateInstanceWithXGtsRef

func (s *GtsStore) ValidateInstanceWithXGtsRef(instanceID string) error

ValidateInstanceWithXGtsRef validates an instance against its schema including x-gts-ref constraints

func (*GtsStore) ValidateSchema

func (s *GtsStore) ValidateSchema(gtsID string) error

ValidateSchema validates a schema including JSON Schema meta-schema and GTS reference validation

type IDValidationResult

type IDValidationResult struct {
	ID         string `json:"id"`
	Valid      bool   `json:"valid"`
	IsSchema   bool   `json:"is_schema"`
	IsWildcard bool   `json:"is_wildcard"`
	Error      string `json:"error,omitempty"`
}

IDValidationResult represents the result of GTS ID validation

func ValidateGtsID

func ValidateGtsID(gtsID string) *IDValidationResult

ValidateGtsID validates a GTS identifier and returns a result

type InvalidGtsIDError

type InvalidGtsIDError struct {
	GtsID string
	Cause string
}

InvalidGtsIDError represents an error when a GTS identifier is invalid

func (*InvalidGtsIDError) Error

func (e *InvalidGtsIDError) Error() string

type InvalidSegmentError

type InvalidSegmentError struct {
	Num     int
	Offset  int
	Segment string
	Cause   string
}

InvalidSegmentError represents an error in a specific segment

func (*InvalidSegmentError) Error

func (e *InvalidSegmentError) Error() string

type InvalidWildcardError

type InvalidWildcardError struct {
	Pattern string
	Cause   string
}

InvalidWildcardError represents an error when a wildcard pattern is invalid

func (*InvalidWildcardError) Error

func (e *InvalidWildcardError) Error() string

type JsonEntity

type JsonEntity struct {
	GtsID                 *GtsID
	SchemaID              string
	SelectedEntityField   string
	SelectedSchemaIDField string
	IsSchema              bool
	Content               map[string]any
	File                  *JsonFile
	ListSequence          *int
	Label                 string
	GtsRefs               []*GtsReference // All GTS ID references found in content
}

JsonEntity represents a JSON object with extracted GTS identifiers

func NewJsonEntity

func NewJsonEntity(content map[string]any, cfg *GtsConfig) *JsonEntity

NewJsonEntity creates a JsonEntity from JSON content using the provided config

func NewJsonEntityWithFile

func NewJsonEntityWithFile(content map[string]any, cfg *GtsConfig, file *JsonFile, listSequence *int) *JsonEntity

NewJsonEntityWithFile creates a JsonEntity with file and sequence information

type JsonFile

type JsonFile struct {
	Path    string
	Name    string
	Content any
}

JsonFile represents a JSON file containing one or more entities

type ListResult

type ListResult struct {
	Entities []EntityInfo `json:"entities"`
	Count    int          `json:"count"`
	Total    int          `json:"total"`
}

ListResult represents the result of listing entities

type MatchIDResult

type MatchIDResult struct {
	Candidate string `json:"candidate"`
	Pattern   string `json:"pattern"`
	Match     bool   `json:"match"`
	Error     string `json:"error,omitempty"`
}

MatchIDResult represents the result of matching a GTS identifier against a pattern

func MatchIDPattern

func MatchIDPattern(candidate, pattern string) MatchIDResult

MatchIDPattern matches a candidate GTS identifier against a pattern with wildcards Returns a MatchIDResult with Match=true if the candidate matches the pattern, or Match=false with an optional Error message on failure or mismatch

type ParseIDResult

type ParseIDResult struct {
	ID         string           `json:"id"`
	OK         bool             `json:"ok"`
	IsWildcard bool             `json:"is_wildcard"`
	IsSchema   bool             `json:"is_schema"`
	Segments   []ParseIDSegment `json:"segments"`
	Error      string           `json:"error,omitempty"`
}

ParseIDResult represents the result of parsing a GTS identifier

func ParseGtsID

func ParseGtsID(gtsID string) ParseIDResult

ParseGtsID parses a GTS identifier into its components

func ParseID

func ParseID(gtsID string) ParseIDResult

ParseID decomposes a GTS identifier into its constituent parts Returns a ParseIDResult with OK=true and populated Segments on success, or OK=false with an Error message on failure

type ParseIDSegment

type ParseIDSegment struct {
	Vendor    string `json:"vendor"`
	Package   string `json:"package"`
	Namespace string `json:"namespace"`
	Type      string `json:"type"`
	VerMajor  int    `json:"ver_major"`
	VerMinor  *int   `json:"ver_minor"`
	IsType    bool   `json:"is_type"`
}

ParseIDSegment represents a parsed segment component from a GTS identifier

type QueryResult

type QueryResult struct {
	Error   string           `json:"error"`
	Count   int              `json:"count"`
	Limit   int              `json:"limit"`
	Results []map[string]any `json:"results"`
}

QueryResult represents the result of a GTS query execution

type RefValidationError added in v0.7.0

type RefValidationError struct {
	FieldPath string
	RefValue  string
	Reason    string
}

RefValidationError represents a validation error for $ref values

func (*RefValidationError) Error added in v0.7.0

func (e *RefValidationError) Error() string

type RefValidator added in v0.7.0

type RefValidator struct {
}

RefValidator validates $ref constraints in GTS schemas

func NewRefValidator added in v0.7.0

func NewRefValidator() *RefValidator

NewRefValidator creates a new $ref validator

func (*RefValidator) ValidateSchemaRefs added in v0.7.0

func (v *RefValidator) ValidateSchemaRefs(schema map[string]interface{}, schemaPath string) []*RefValidationError

ValidateSchemaRefs validates all $ref values in a schema

type RegistryConfig

type RegistryConfig struct {
	// ValidateGtsReferences enables validation of GTS references on entity registration
	ValidateGtsReferences bool
}

RegistryConfig configures the GtsStore behavior

func DefaultRegistryConfig

func DefaultRegistryConfig() *RegistryConfig

DefaultRegistryConfig returns the default registry configuration

type SchemaGraphNode

type SchemaGraphNode struct {
	ID       string                      `json:"id"`
	Refs     map[string]*SchemaGraphNode `json:"refs,omitempty"`
	SchemaID *SchemaGraphNode            `json:"schema_id,omitempty"`
	Errors   []string                    `json:"errors,omitempty"`
}

SchemaGraphNode represents a node in the schema relationship graph

type StoreGtsCastFromSchemaNotAllowedError

type StoreGtsCastFromSchemaNotAllowedError struct {
	FromID string
}

StoreGtsCastFromSchemaNotAllowedError is returned when attempting to cast from a schema ID

func (*StoreGtsCastFromSchemaNotAllowedError) Error

type StoreGtsObjectNotFoundError

type StoreGtsObjectNotFoundError struct {
	EntityID string
}

StoreGtsObjectNotFoundError is returned when a GTS entity is not found in the store

func (*StoreGtsObjectNotFoundError) Error

type StoreGtsSchemaForInstanceNotFoundError

type StoreGtsSchemaForInstanceNotFoundError struct {
	EntityID string
}

StoreGtsSchemaForInstanceNotFoundError is returned when a schema ID cannot be determined for an instance

func (*StoreGtsSchemaForInstanceNotFoundError) Error

type StoreGtsSchemaNotFoundError

type StoreGtsSchemaNotFoundError struct {
	EntityID string
}

StoreGtsSchemaNotFoundError is returned when a GTS schema is not found in the store

func (*StoreGtsSchemaNotFoundError) Error

type UUIDResult

type UUIDResult struct {
	ID    string `json:"id"`
	UUID  string `json:"uuid"`
	Error string `json:"error"`
}

UUIDResult represents the result of GTS ID to UUID conversion

func IDToUUID

func IDToUUID(gtsID string) *UUIDResult

IDToUUID converts a GTS ID to a UUID

type ValidationResult

type ValidationResult struct {
	ID    string `json:"id"`
	OK    bool   `json:"ok"`
	Error string `json:"error"`
}

ValidationResult represents the result of validating an instance

type XGtsRefValidationError

type XGtsRefValidationError struct {
	FieldPath  string
	Value      interface{}
	RefPattern string
	Reason     string
}

XGtsRefValidationError represents a validation error for x-gts-ref constraints

func (*XGtsRefValidationError) Error

func (e *XGtsRefValidationError) Error() string

type XGtsRefValidator

type XGtsRefValidator struct {
	// contains filtered or unexported fields
}

XGtsRefValidator validates x-gts-ref constraints in GTS schemas

func NewXGtsRefValidator

func NewXGtsRefValidator(store *GtsStore) *XGtsRefValidator

NewXGtsRefValidator creates a new x-gts-ref validator

func (*XGtsRefValidator) ValidateInstance

func (v *XGtsRefValidator) ValidateInstance(instance map[string]interface{}, schema map[string]interface{}, instancePath string) []*XGtsRefValidationError

ValidateInstance validates an instance against x-gts-ref constraints in schema

func (*XGtsRefValidator) ValidateSchema

func (v *XGtsRefValidator) ValidateSchema(schema map[string]interface{}, schemaPath string, rootSchema map[string]interface{}) []*XGtsRefValidationError

ValidateSchema validates x-gts-ref fields in a schema definition

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL