Expand description
§OxiRS SAMM - Semantic Aspect Meta Model Implementation
Status: Production Release (v0.2.4) ✅ All public APIs documented. Production-ready with API stability guarantees.
This crate provides a Rust implementation of the Semantic Aspect Meta Model (SAMM), which enables the creation of models to describe the semantics of digital twins.
§Overview
SAMM (formerly BAMM) is a meta model for defining domain-specific aspects of digital twins. It provides a set of predefined objects that allow domain experts to define Aspect Models and complement digital twins with a semantic foundation.
§Core Concepts
- Aspect: The root element describing a digital twin’s specific aspect
- Property: A named feature of an Aspect with a defined Characteristic
- Characteristic: Describes the semantics of a Property’s value
- Entity: A complex data structure with multiple properties
- Operation: A function that can be performed on an Aspect
- Event: An occurrence that can be emitted by an Aspect
§Features
- ✅ SAMM 2.3.0 Support: Full support for latest SAMM specification
- ✅ RDF/Turtle Parsing: Load SAMM models from Turtle files
- ✅ SHACL Validation: Validate models against SAMM shapes
- ✅ Code Generation: Generate code in 7+ languages (Rust, TypeScript, Python, Java, Scala, GraphQL, SQL)
- ✅ AAS Integration: Full Asset Administration Shell V3.0 support (XML, JSON, AASX packages)
- ✅ Performance Optimization: Parallel processing, caching, profiling utilities
- ✅ Production Monitoring: Metrics collection, health checks, structured logging
§Quick Start
§Basic Usage - Parse and Validate
use oxirs_samm::metamodel::{Aspect, ModelElement};
use oxirs_samm::parser::parse_aspect_model;
use oxirs_samm::validator::validate_aspect;
// Parse a SAMM model from a Turtle file
let aspect = parse_aspect_model("path/to/AspectModel.ttl").await?;
// Validate the aspect model
let validation_result = validate_aspect(&aspect).await?;
if !validation_result.is_valid {
for error in &validation_result.errors {
eprintln!("Validation error: {}", error.message);
}
}
// Access aspect properties
println!("Aspect: {}", aspect.name());
for property in aspect.properties() {
println!(" Property: {} (type: {:?})",
property.name(),
property.characteristic.as_ref().map(|c| &c.data_type));
}§Advanced Usage - Code Generation
use oxirs_samm::parser::parse_aspect_model;
use oxirs_samm::generators::{
generate_typescript, TsOptions,
generate_graphql,
generate_sql, SqlDialect,
};
let aspect = parse_aspect_model("Movement.ttl").await?;
// Generate TypeScript interfaces
let ts_code = generate_typescript(&aspect, TsOptions::default())?;
std::fs::write("movement.ts", ts_code)?;
// Generate GraphQL schema
let graphql_schema = generate_graphql(&aspect)?;
std::fs::write("movement.graphql", graphql_schema)?;
// Generate SQL DDL
let sql_ddl = generate_sql(&aspect, SqlDialect::PostgreSql)?;
std::fs::write("movement.sql", sql_ddl)?;§Performance Tuning
use oxirs_samm::{PerformanceConfig, BatchProcessor, ModelCache};
// Configure performance settings
let config = PerformanceConfig {
parallel_processing: true,
num_workers: 8,
cache_size: 100,
profiling_enabled: true,
..Default::default()
};
// Use batch processor for multiple models
let processor = BatchProcessor::new(config);
let models = vec![
"model1_content".to_string(),
"model2_content".to_string(),
"model3_content".to_string(),
];
let results = processor.process_batch(models, |model| {
// Process each model
Ok(model.len())
}).await?;
// Use model cache for frequent lookups
let cache = ModelCache::new(100);
if let Some(cached_model) = cache.get("urn:samm:org.example:1.0.0#Movement") {
println!("Found cached model: {}", cached_model.len());
}§Production Monitoring
use oxirs_samm::{
init_production, ProductionConfig,
MetricsCollector, OperationType,
health_check,
};
// Initialize production monitoring
let config = ProductionConfig::default();
init_production(&config)?;
// Collect metrics
let metrics = MetricsCollector::global();
metrics.record_operation(OperationType::Parse);
metrics.record_operation_with_duration(OperationType::Parse, 150.0); // ms
// Perform health checks
let health_result = health_check();
println!("System health: {:?}", health_result);
// Get metrics snapshot
let snapshot = metrics.snapshot();
println!("Total operations: {}", snapshot.operations_total);
println!("Parse operations: {}", snapshot.parse_operations);
println!("Errors: {}", snapshot.errors_total);§References
Re-exports§
pub use analytics::Anomaly;pub use analytics::AnomalyType;pub use analytics::BenchmarkComparison;pub use analytics::BenchmarkLevel;pub use analytics::BestPracticeCheck;pub use analytics::BestPracticeReport;pub use analytics::CheckCategory;pub use analytics::ComplexityAssessment;pub use analytics::ComplexityLevel;pub use analytics::ConfidenceLevel;pub use analytics::CorrelationDirection;pub use analytics::CorrelationInsight;pub use analytics::CorrelationStrength;pub use analytics::DependencyMetrics;pub use analytics::DistributionAnalysis;pub use analytics::DistributionFit;pub use analytics::DistributionParameters;pub use analytics::DistributionStats;pub use analytics::DistributionType;pub use analytics::ModelAnalytics;pub use analytics::PropertyCorrelationMatrix;pub use analytics::QualityTest;pub use analytics::Recommendation;pub use analytics::RecommendationType;pub use analytics::Severity;pub use analytics::StatisticalAnomaly;pub use analytics::StatisticalMetrics;pub use cache::AspectCache;pub use cache::CacheStatistics;pub use cache::CharacteristicCache;pub use cache::EntityCache;pub use cache::LruModelCache;pub use cache::OperationCache;pub use cache::PropertyCache;pub use cache::TtlCache;pub use cache::TtlCacheStatistics;pub use cloud_client::CloudStorageClient;pub use cloud_client::CloudStorageError;pub use cloud_client::MockCloudStorage;pub use cloud_client::RetryableCloudClient;pub use cloud_storage::BatchResult;pub use cloud_storage::CacheStats;pub use cloud_storage::CloudModelStorage;pub use cloud_storage::CloudStorageBackend;pub use cloud_storage::MemoryBackend;pub use cloud_storage::ModelInfo;pub use cloud_storage::ObjectMetadata;pub use codegen::HttpMethod;pub use codegen::JsonSchemaGenerator;pub use codegen::JsonSchemaOptions;pub use codegen::JsonSchemaValidator;pub use codegen::OpenApiGenerator;pub use codegen::OpenApiOptions;pub use codegen::ValidationError as JsonSchemaValidationError;pub use comparison::MetadataChange;pub use comparison::MetadataChangeType;pub use comparison::ModelComparison;pub use comparison::PropertyChange;pub use documentation::DocumentationFormat;pub use documentation::DocumentationGenerator;pub use documentation::DocumentationStyle;pub use dtdl_parser::parse_dtdl_interface;pub use error::ErrorCategory;pub use error::Result;pub use error::SammError;pub use error::SourceLocation;pub use generators::GeneratedFile;pub use generators::MultiFileGenerator;pub use generators::MultiFileOptions;pub use generators::OutputLayout;pub use graph_analytics::CentralityMetrics;pub use graph_analytics::ChangeMagnitude;pub use graph_analytics::ColorScheme;pub use graph_analytics::Community;pub use graph_analytics::Cycle;pub use graph_analytics::CycleBreakSuggestion;pub use graph_analytics::GraphComparison;pub use graph_analytics::GraphMetrics;pub use graph_analytics::ImpactAnalysis;pub use graph_analytics::ModelGraph;pub use graph_analytics::RiskLevel;pub use graph_analytics::VisualizationStyle;pub use metamodel::Aspect;pub use metamodel::Characteristic;pub use metamodel::Entity;pub use metamodel::Operation;pub use metamodel::Property;pub use migration::MigrationOptions;pub use migration::MigrationResult;pub use migration::ModelMigrator;pub use migration::SammVersion;pub use parser::ErrorRecoveryStrategy;pub use parser::RecoveryAction;pub use parser::RecoveryContext;pub use parser::StreamingParser;pub use performance::BatchProcessor;pub use performance::ModelCache;pub use performance::PerformanceConfig;pub use production::health_check;pub use production::init_production;pub use production::HealthCheck;pub use production::HealthStatus;pub use production::MetricsCollector;pub use production::OperationType;pub use production::ProductionConfig;pub use query::ComplexityMetrics;pub use query::Dependency;pub use query::ModelQuery;pub use query_cache::CacheStatistics as QueryCacheStatistics;pub use query_cache::CachedModelQuery;pub use serializer::serialize_aspect_to_file;pub use serializer::serialize_aspect_to_jsonld_file;pub use serializer::serialize_aspect_to_jsonld_string;pub use serializer::serialize_aspect_to_rdfxml_file;pub use serializer::serialize_aspect_to_rdfxml_string;pub use serializer::serialize_aspect_to_string;pub use serializer::JsonLdSerializer;pub use serializer::RdfXmlSerializer;pub use serializer::TurtleSerializer;pub use templates::scaffolding::ModelTemplate;pub use templates::scaffolding::TemplateBuilder;pub use templates::scaffolding::TemplateRegistry;pub use templates::PostRenderHook;pub use templates::PreRenderHook;pub use templates::TemplateContext;pub use templates::TemplateEngine;pub use templates::ValidationHook;pub use transformation::ModelTransformation;pub use transformation::TransformationRule;pub use validation::SammSchemaValidator;pub use validation::SchemaValidationError;pub use validation::SchemaValidationWarning;pub use validation::ValidationReport;pub use validation::ValidationRule;pub use versioning::AspectMigrationRegistry;pub use versioning::AspectVersion;pub use versioning::MigrationStep;pub use versioning::VersionedAspect;
Modules§
- aas_
parser - AAS (Asset Administration Shell) parser module
- analytics
- Auto-generated module structure (extended with advanced analytics)
- aspect_
chain - SAMM aspect hierarchical property chain traversal (v1.1.0 round 8). SAMM aspect hierarchical property chain traversal.
- aspect_
differ - Structural differ for SAMM Aspect Models.
- aspect_
export - Aspect model serialization to JSON/YAML/Text (v1.1.0 round 12). Aspect model serialization to JSON, YAML, and plain-text formats.
- aspect_
validator - SAMM aspect model validation — required properties, cardinality, constraints, cycles (v1.1.0 round 13).
- cache
- LRU Cache for SAMM Model Elements
- characteristic_
validator - SAMM characteristic validation (v1.1.0 round 13). SAMM characteristic validation.
- cloud_
backends - Real Cloud Storage Backends for SAMM Models
- cloud_
client - Cloud Storage Client Abstraction Layer
- cloud_
storage - Cloud Storage Integration for SAMM Models
- codegen
- SAMM Code Generation Modules
- comparison
- Model Comparison and Diff Utilities
- constraint_
registry - Registry of SAMM constraint types with validation support (v1.1.0 round 7).
- constraint_
validator - SAMM characteristic constraint validators (RangeConstraint, LengthConstraint, EncodingConstraint, RegularExpressionConstraint) (v1.1.0 round 16). SAMM characteristic constraint validators.
- documentation
- Model Documentation Generation
- dtdl_
parser - DTDL Parser - Azure Digital Twins to SAMM Converter
- entity_
resolver - SAMM entity resolution: hierarchy traversal, property flattening, and comparison (v1.1.0 round 12).
- error
- Error types for SAMM operations
- event_
model - SAMM event model for IoT events (v1.1.0 round 11).
- generators
- Code generators for SAMM models
- graph_
analytics - Graph-Based Model Analytics using SciRS2-Graph
- metamodel
- SAMM Meta Model Types
- migration
- Model versioning and migration tools
- model_
serializer - SAMM aspect model serialization to JSON/YAML/Turtle/Compact formats (v1.1.0 round 14). SAMM aspect model serialization to multiple formats.
- operation_
mapper - SAMM Operation → REST/MQTT API Mapping
- operation_
registry - SAMM operation registry for aspect operations (v1.1.0 round 9).
- package
- Package management for SAMM namespace packages
- parser
- SAMM Model Parser
- payload_
generator - SAMM payload generation from aspect model definitions (v1.1.0 round 11).
- performance
- Performance optimization module for SAMM processing
- production
- Production-ready features for SAMM processing with SciRS2 integration
- property_
mapper - SAMM property mapping between aspect models and target schemas (v1.1.0 round 15).
- query
- Model Query Utilities
- query_
cache - Query Result Caching
- serializer
- SAMM Model Serialization
- simd_
ops - SIMD-Accelerated String Operations for SAMM Processing
- submodel_
templates - AAS Submodel Template Library
- templates
- Template engine for custom code generation
- transformation
- Model Transformation Utilities
- unit_
catalog - SAMM/BAMM Unit Catalog with SI and derived units.
- unit_
converter - SAMM physical unit conversion engine (v1.1.0 round 10).
- utils
- Utility functions for common SAMM operations
- validation
- SAMM Model Validation
- validator
- SAMM Model Validator
- versioning
- SAMM Aspect Versioning
- vocabulary_
mapper - SAMM vocabulary mapper: converts SAMM model elements to RDF/OWL triples.
Constants§
- SAMM_
C_ NAMESPACE - SAMM characteristics namespace
- SAMM_
E_ NAMESPACE - SAMM entities namespace
- SAMM_
NAMESPACE - SAMM namespace URN prefix
- SAMM_
U_ NAMESPACE - SAMM units namespace
- SAMM_
VERSION - SAMM version supported by this implementation