Crate oxirs_samm

Expand description

§OxiRS SAMM - Semantic Aspect Meta Model Implementation

Status: Production Release (v0.3.1) ✅ 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 cross_model::CrossModelError;
pub use cross_model::CrossModelReference;
pub use cross_model::CrossModelRegistry;
pub use cross_model::CrossModelValidator;
pub use cross_model::ModelEntry;
pub use cross_model::ValidationReport as CrossModelValidationReport;
pub use parity::generate_report;
pub use parity::load_catalog;
pub use parity::FeatureCategory;
pub use parity::FeatureEntry;
pub use parity::FeatureStatus;
pub use parity::ImplStatus;
pub use parity::ParityMatrix;
pub use analytics::Anomaly;
pub use analytics::AnomalyType;
pub use analytics::BatchCorrelationError;
pub use analytics::BatchCorrelationMatrix;
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::OpenApiVersion;
pub use codegen::PaginationConfig;
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::BatchValidator;
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.
cli: Command-line interface sub-command implementations (v0.3.0). Command-line interface support for the samm binary.
cloud_backends: Real Cloud Storage Backends for SAMM Models
cloud_backends_aws: AWS S3 (and S3-compatible) storage backend: cloud_backends_aws::S3Config / cloud_backends_aws::S3Backend. AWS S3 (and S3-compatible) storage backend.
cloud_backends_azure: Azure Blob Storage backend: cloud_backends_azure::AzureConfig / cloud_backends_azure::AzureBlobBackend. Azure Blob Storage backend.
cloud_backends_common: Common HMAC/SHA-256, hex, URL and XML helpers shared by the cloud backends. Common helpers shared by all cloud backend modules.
cloud_backends_gcp: Google Cloud Storage backend: cloud_backends_gcp::GcsConfig / cloud_backends_gcp::GcsBackend. Google Cloud Storage backend.
cloud_backends_http: Generic HTTP REST storage backend: cloud_backends_http::HttpConfig / cloud_backends_http::HttpBackend. Generic HTTP REST storage backend.
cloud_backends_impl: Backend aggregation plus the local-filesystem adapter cloud_backends_impl::LocalFsBackend. Backend implementations for the SAMM cloud storage subsystem.
cloud_backends_sync: Multi-backend replication and synchronization for cloud storage. Multi-backend synchronization for the SAMM cloud storage subsystem.
cloud_backends_types: Cloud backend configuration envelopes and capability/access-policy enums. Type definitions for the SAMM cloud backend subsystem.
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.
cross_model: Cross-model URN reference validation for SAMM aspect models (v0.3.1).
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
jsonld: JSON-LD 1.1 compaction and framing algorithms. JSON-LD 1.1 processing for SAMM Aspect Models.
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
parity: ESMF SDK 2.x feature parity matrix and status report (v0.3.0). ESMF SDK 2.x feature parity tracking for oxirs-samm.
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: SAMM submodel templates: reusable groups of properties for aspect models.
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

Crate oxirs_samm

Crate oxirs_samm Copy item path

§OxiRS SAMM - Semantic Aspect Meta Model Implementation

§Overview

§Core Concepts

§Features

§Quick Start

§Basic Usage - Parse and Validate

§Advanced Usage - Code Generation

§Performance Tuning

§Production Monitoring

§References

Re-exports§

Modules§

Constants§

Crate oxirs_samm