LutaML: Unified data model accessor

Purpose

LutaML aims to be a unified data model accessor that allows parsing data models in multiple languages, including:

EXPRESS (EXPRESS Language Foundation, ISO 10303-11)
Enterprise Architect UML models in QEA format or exported as OMG XMI
UML in LutaML format

Install

With bundler, in Gemfile:

gem "lutaml"

Directly:

$ gem install lutaml

Documentation

Complete documentation is available at https://lutaml.github.io/lutaml/

The documentation includes:

Getting Started: Quick Start Tutorial
User Guides: Task-oriented how-to guides
Core Topics: Fundamental concepts and architecture
Reference: Detailed specifications and API documentation

You can also build and browse the documentation locally:

cd docs
bundle install
bundle exec jekyll serve
# Open http://localhost:4000/lutaml/

Usage

Parsing

The Lutaml::Parser.parse method provides a single point of entry for parsing data model files, including:

EXPRESS files with .exp extension
YAML Compressed EXPRESS CACHE files
QEA files with .qea extension (Enterprise Architect databases)
XMI files with .xmi extension
XML files with .xml extension
LutaML files with .lutaml extension

Depending on the input file type, Lutaml::Parser.parse returns:

Expressir::Express::Model::Repository for EXPRESS files
Expressir::Express::Cache for EXPRESS CACHE files
Lutaml::Uml::Document for QEA files (returned as single-element array)
Lutaml::Uml::Document for XMI files
Lutaml::Uml::Document for XML files
Lutaml::Uml::Document for LutaML files

Examples to use the Lutaml::Parser.parse:

require "lutaml"

# example.exp is an EXPRESS schema file
model = Lutaml::Parser.parse([File.new("example.exp")])
# => returns Expressir::Express::Model::Repository model

# example.exp.yaml is an EXPRESS cache file created with Expressir
model = Lutaml::Parser.parse([File.new("example.exp.yaml")], ::Lutaml::Parser::EXPRESS_CACHE_PARSE_TYPE)
# => returns Expressir::Express::Cache model

# example.xmi is an XMI file
model = Lutaml::Parser.parse([File.new("example.xmi")])
# => returns Lutaml::Uml::Document model

# example.xml is an XML file
model = Lutaml::Parser.parse([File.new("example.xml")])
# => returns Lutaml::Uml::Document model

# example.lutaml is an LutaML file
model = Lutaml::Parser.parse([File.new("example.lutaml")])
# => returns Lutaml::Uml::Document model

# example.yaml is an LutaML YAML file
model = Lutaml::Parser.parse([File.new("example.yaml")])
# => returns Lutaml::Uml::Document model

Working with UML

General

Lutaml supports various UML formats and unifies them under a common data model: Lutaml::Uml::Document.

Lutaml supports the following UML formats:

Enterprise Architect QEA files (.qea extension)
Enterprise Architect exported XMI files (.xmi extension)
Enterprise Architect exported XML files (.xml extension)
LutaML UML files (.lutaml extension)

LutaML UML

LutaML UML is a simple, human-readable representation of UML models.

The syntax is described in LutaML UML syntax.

Enterprise Architect

Enterprise Architect is a popular UML modeling tool by Sparx Systems. It supports exporting UML models in XMI and XML formats.

Diagram generation

LutaML Diagrams

LutaML Diagram is a lightweight textual syntax for defining model diagrams.

The syntax is described in LutaML diagram syntax.

A CLI is provided to generate diagrams from LutaML DSL files:

# Generate diagrams from LutaML DSL files
$ lutaml -o . test.lutaml
$ lutaml -o assets -t png test.lutaml

General

LutaML provides comprehensive command-line interfaces for working with data models and UML repositories.

UML repository commands (for XMI, QEA, and LUR files):

The lutaml uml command suite provides a complete interface for working with UML models. See [CLI commands reference](#cli-commands-reference) for details.

# Build LUR package from XMI or QEA
$ lutaml uml build model.xmi -o model.lur
$ lutaml uml build project.qea -o project.lur

# Explore and query
$ lutaml uml ls model.lur
$ lutaml uml tree model.lur --depth 2
$ lutaml uml search model.lur "Building"
$ lutaml uml stats model.lur

# Export and document
$ lutaml uml export model.lur --format csv -o classes.csv
$ lutaml uml build-spa model.lur -o docs/index.html
$ lutaml uml serve model.lur --port 8080

# Interactive exploration
$ lutaml uml repl model.lur

Thin wrapper principle

The CLI is designed as a thin wrapper around the Ruby API. Every CLI command directly maps to Ruby API methods, making it easy to:

Transition from CLI to programmatic usage
Understand what the CLI does by reading the API documentation
Script complex workflows using Ruby when needed

Example 1. CLI to API mapping example

# CLI command
$ lutaml uml build model.xmi -o model.lur

Equivalent Ruby code:

require "lutaml/xmi"

repo = Lutaml::UmlRepository::Repository.from_xmi("model.xmi")
repo.export_to_package("model.lur")

UML support

QEA Direct Database Parsing

LutaML supports direct parsing of Enterprise Architect .qea files (SQLite databases) without requiring XMI export. This provides significant performance improvements and access to EA-specific metadata.

What are QEA files?

QEA (Quantified EA) files are Enterprise Architect’s native database format based on SQLite. They contain the complete UML model including:

Packages, classes, attributes, operations
Associations and generalizations
Diagrams and diagram elements
EA-specific metadata (stereotypes, tagged values, etc.)

Why direct parsing?

Direct QEA parsing offers several advantages over XMI:

Performance: 10-20x faster than XMI parsing
No export step: Parse directly from EA database
EA metadata: Access to EA-specific information not available in XMI
Memory efficient: Streams data from SQLite without loading entire file

Parser API usage

require "lutaml"

# Parse QEA file directly
document = Lutaml::Parser.parse([File.new("model.qea")]).first
# => returns Lutaml::Uml::Document

# Use with UmlRepository
repo = Lutaml::UmlRepository::Repository.new(document: document)

# Query the model
classes = repo.find_classes_by_stereotype("featureType")

QEA module API

The Lutaml::Qea module provides direct access to QEA parsing:

require "lutaml/qea"

# Parse QEA file
document = Lutaml::Qea.parse("model.qea")

# With options
document = Lutaml::Qea.parse("model.qea",
  include_diagrams: true,
  validate: true
)

# Load database for low-level access
database = Lutaml::Qea.load_database("model.qea") do |table, current, total|
  puts "Loading #{table}: #{current}/#{total}"
end

# Get quick statistics
info = Lutaml::Qea.database_info("model.qea")
puts info  # => {"objects" => 693, "attributes" => 1910, ...}

CLI usage with QEA files

All CLI commands accept both XMI and QEA files:

# Build LUR from QEA (10-20x faster than XMI)
lutaml uml build model.qea -o model.lur

# Build LUR from XMI
lutaml uml build model.xmi -o model.lur

# All other commands work the same
lutaml uml search model.lur "Building"
lutaml uml tree model.lur

File validation

require "lutaml/qea/file_detector"

# Check if file is valid QEA
if Lutaml::Qea::FileDetector.qea_file?("model.qea")
  puts "Valid QEA file"
end

# Validate structure
result = Lutaml::Qea::FileDetector.validate_qea("model.qea")
if result[:valid]
  puts "QEA file is valid"
else
  result[:errors].each { |e| puts "ERROR: #{e}" }
end

# Get file information
info = Lutaml::Qea::FileDetector.file_info("model.qea")
puts "Size: #{info[:size_mb]} MB"
puts "Tables: #{info[:table_count]}"
puts "Objects: #{info[:object_count]}"

Performance benchmarking

require "lutaml/qea/benchmark"

# Compare QEA vs XMI parsing
results = Lutaml::Qea::Benchmark.compare("model.qea", "model.xmi")

puts "QEA: #{results[:qea][:time]}s"
puts "XMI: #{results[:xmi][:time]}s"
puts "Speedup: #{results[:speedup]}x faster"

# Display formatted results
puts Lutaml::Qea::Benchmark.format_results(results)

Performance characteristics

Typical performance for a 20MB EA model:

QEA parsing: 1-2 seconds
XMI parsing: 20-40 seconds
Speedup: 10-20x faster
Memory: Lower memory footprint with QEA

Configuration

QEA parsing is configured via config/qea_schema.yml:

tables:
  - table_name: t_object
    enabled: true
    model_class: Object

  - table_name: t_attribute
    enabled: true
    model_class: Attribute

  # ... other tables

Limitations

QEA files must be SQLite 3 format
Requires EA-specific table structure
Some EA proprietary features may not be fully supported
Only reads from QEA; does not write back to EA database

QEA vs XMI Comparison

LutaML supports both QEA (SQLite) and XMI (XML) formats from Enterprise Architect. While functionally equivalent, QEA parsing offers several advantages:

Performance

QEA: 1-2 seconds for 20MB files (direct SQLite access)
XMI: 20-40 seconds for same files (XML parsing overhead)
Speedup: 10-20x faster parsing with QEA

Data Richness

QEA preserves more semantic information due to direct database access:

Association type differentiation: QEA preserves the distinction between Association, Aggregation, and Composition connector types through the member_end_type field. XMI export from EA hardcodes all association types as "aggregation", losing this semantic information.
Tagged values: QEA includes object properties as tagged values, capturing EA-specific metadata that may not be exported to XMI. For example, a class in QEA might have 3 tagged values while the same class in XMI has 0, representing metadata loss during XMI export.
Association generalization structure: QEA provides rich AssociationGeneralization objects with full type information, while XMI reduces these to simple string IDs, losing structural detail.

Compatibility

99.6% parity between formats for core UML data
QEA is the preferred format when working with Enterprise Architect models
Both formats produce equivalent Lutaml::Uml::Document structures

LutaML UML Repository (LUR)

General

LutaML UML Repository provides a unified interface for UML models with built-in indexing and package management.

Package format

LUR packages are ZIP archives containing:

model.lur
├── metadata.yaml          # Package info, statistics
├── models/
│   └── document.marshal   # Serialized UML model
├── indexes/
│   ├── all.marshal        # Pre-built indexes
│   └── index_tree.yaml    # Human-readable package tree (NEW)
└── statistics.yaml        # Detailed statistics

The index_tree.yaml file provides a human-readable view of the package hierarchy with class counts, making it easy to inspect the structure without loading the full repository. This is particularly useful for:

Quick package structure inspection
Debugging package organization
Understanding model hierarchy
Generating documentation

Quick start

CLI usage

# Build LUR package
lutaml uml package build model.qea -o model.lur
lutaml uml package build model.xmi -o model.lur

# Show package info
lutaml uml package info model.lur

# List packages
lutaml uml list model.lur

# Show package tree
lutaml uml tree model.lur --max-depth 3

# Show class details
lutaml uml show class "MyPackage::MyClass" model.lur

# Search
lutaml uml search "building" model.lur

# Get statistics
lutaml uml stats model.lur

# Command aliases (shortcuts)
lutaml uml ls model.lur           # alias for 'list'
lutaml uml t model.lur            # alias for 'tree'
lutaml uml s class MyClass model.lur  # alias for 'show'
lutaml uml ? "building" model.lur  # alias for 'search'
lutaml uml f --stereotype featureType model.lur  # alias for 'find'

# Interactive shell (REPL)
lutaml uml shell model.lur

Build repository from XMI or QEA

require "lutaml/xmi"

# Build from XMI file
repo = Lutaml::UmlRepository::Repository.from_xmi("model.xmi")

# Build from QEA file
repo = Lutaml::UmlRepository::Repository.from_qea("model.qea")

# Query the model
package = repo.find_package("ModelRoot::MyPackage")
klass = repo.find_class("ModelRoot::MyPackage::MyClass")
classes = repo.find_classes_by_stereotype("featureType")

# Get statistics
stats = repo.statistics
puts "Total classes: #{stats[:total_classes]}"

Save as LUR package

# Export to .lur package (fast loading)
repo.export_to_package("model.lur",
  name: "My Model",
  version: "1.0",
  serialization_format: :marshal  # or :yaml
)

# Load from package (< 100ms vs >5s parsing XMI)
repo = Lutaml::UmlRepository::Repository.from_package("model.lur")

# Smart file detection (auto-detects format)
repo = Lutaml::UmlRepository::Repository.from_file("model.xmi")
repo = Lutaml::UmlRepository::Repository.from_file("model.lur")

# Intelligent caching (uses cache if fresh, rebuilds if stale)
repo = Lutaml::UmlRepository::Repository.from_file_cached("model.xmi")
# Creates model.lur and reuses it on subsequent runs

LUR configuration

General

A configuration file is used to describe package-specific settings for an LUR package, including metadata and features enabled.

The configuration format is as follows:

metadata:
  name: My Model
  version: 1.0
  description: A sample UML model
  license: MIT
  author: John Doe
package:
  input: /path/to/model.xmi  # or .qea
  storage_format: marshal  # or yaml
  include_original_file: true

Search

LUR packages allow full-text search across model elements.

# Get helpful suggestions for typos
repo.find_class("ModelRoot::Buildng", raise_on_error: true)
# => NameError: Class not found: ModelRoot::Buildng
#    Did you mean one of these?
#      - ModelRoot::Building
#      - ModelRoot::BuildingPart

repo.find_package("ModelRoot::i-UP", raise_on_error: true)
# => NameError: Package not found: ModelRoot::i-UP
#    Did you mean one of these?
#      - ModelRoot::i-UR

API reference

Smart loading methods

# Auto-detect file type
repo = Lutaml::UmlRepository::Repository.from_file("model.xmi")
repo = Lutaml::UmlRepository::Repository.from_file("model.lur")

# Smart caching (only rebuilds when XMI is newer than cache)
repo = Lutaml::UmlRepository::Repository.from_file_cached("model.xmi")
repo = Lutaml::UmlRepository::Repository.from_file_cached("model.xmi",
                                                     lur_path: "cache/model.lur")

Error handling with suggestions

# Find class with error handling
klass = repo.find_class("ModelRoot::MyClass", raise_on_error: true)
# Raises NameError with suggestions if not found

# Find package with error handling
package = repo.find_package("ModelRoot::MyPackage", raise_on_error: true)
# Raises NameError with suggestions if not found

# Find package by path
package = repo.find_package("ModelRoot::i-UR::urf")

# List packages
packages = repo.list_packages("ModelRoot::i-UR", recursive: true)

# Get package tree
tree = repo.package_tree("ModelRoot", max_depth: 3)

Class queries

# Find by qualified name
klass = repo.find_class("ModelRoot::i-UR::urf::Building")

# Find by stereotype
feature_types = repo.find_classes_by_stereotype("featureType")

# Get classes in package
classes = repo.classes_in_package("ModelRoot::i-UR::urf", recursive: false)

Inheritance queries

# Get parent class
parent = repo.supertype_of("ModelRoot::MyPackage::ChildClass")

# Get child classes
children = repo.subtypes_of("ModelRoot::MyPackage::ParentClass")

# Get all children recursively
all_children = repo.subtypes_of(parent_class, recursive: true)

# Get inheritance chain
ancestors = repo.ancestors_of("ModelRoot::MyPackage::MyClass")

# Get all descendants
descendants = repo.descendants_of(base_class, max_depth: 2)

Association & diagram queries

# Get associations
assocs = repo.associations_of("ModelRoot::MyPackage::MyClass")

# Get owned associations only
owned = repo.associations_of(my_class, owned_only: true)

# Get diagrams
diagrams = repo.diagrams_in_package("ModelRoot::MyPackage")
diagram = repo.find_diagram("Class Diagram")
all_diagrams = repo.all_diagrams

Search and element display

# Text search
results = repo.search("urban planning", types: [:class, :attribute])
puts "Found #{results[:total]} matches"

# Pattern search
classes = repo.search("^Urban.*Area$", types: [:class])

# Display element details using presenters
presenter = Lutaml::Xmi::Presenters::PresenterFactory.create(klass)
puts presenter.to_text
puts presenter.to_yaml
puts presenter.to_json

Query DSL (Advanced queries)

The Query DSL provides a fluent, expressive interface for building complex queries with method chaining, lazy evaluation, and composable filters.

# Basic query with hash conditions
results = repo.query do |q|
  q.classes.where(stereotype: 'featureType')
end.all

# Complex query with method chaining
results = repo.query do |q|
  q.classes
    .in_package('ModelRoot::i-UR', recursive: true)
    .where { |c| c.attributes&.size.to_i > 10 }
    .order_by(:name, direction: :desc)
    .limit(5)
end.execute

# Immediate execution with query!
results = repo.query! do |q|
  q.classes.with_stereotype('featureType')
end

Query builder methods

classes - Start a class query
packages - Start a package query
where(conditions) - Filter by hash conditions (e.g., stereotype: 'featureType')
where { |obj| … } - Filter with custom block logic
with_stereotype(stereotype) - Shortcut for stereotype filtering
in_package(path, recursive: false) - Filter by package membership
order_by(field, direction: :asc) - Sort results (:asc or :desc)
limit(count) - Limit number of results
execute / all - Execute query and return results
first - Get first result
last - Get last result
count - Count matching results
any? - Check if any results exist
empty? - Check if no results exist

Query examples

# Find all feature types with many attributes
large_features = repo.query! do |q|
  q.classes
    .with_stereotype('featureType')
    .where { |c| c.attributes&.size.to_i > 20 }
    .order_by(:name)
end

# Find classes in package hierarchy
classes = repo.query do |q|
  q.classes
    .in_package('ModelRoot::i-UR', recursive: true)
    .where(is_abstract: false)
end.all

# Complex filtering with regex
results = repo.query! do |q|
  q.classes
    .where(name: /^Building/)
    .where { |c| c.associations&.any? }
    .limit(10)
end

# Combining multiple conditions
feature_types = repo.query do |q|
  q.classes
    .with_stereotype('featureType')
    .where { |c| c.attributes&.size.to_i > 5 }
    .where { |c| c.associations&.size.to_i > 2 }
end

# Get count without loading all results
count = feature_types.count

# Check if any exist
has_results = feature_types.any?

# Get ordered results
sorted = feature_types.order_by(:name, direction: :desc).all

Deferred vs immediate execution

# Deferred execution - build query, execute later
builder = repo.query do |q|
  q.classes.with_stereotype('featureType')
end

# Can add more conditions
builder.where { |c| c.attributes.size > 10 }

# Execute when ready
results = builder.execute

# Immediate execution - execute and return results
results = repo.query! do |q|
  q.classes.with_stereotype('featureType')
end

Statistics & validation

# Get statistics
stats = repo.statistics
puts "Packages: #{stats[:total_packages]}"
puts "Classes: #{stats[:total_classes]}"
puts "Stereotypes: #{stats[:classes_by_stereotype]}"

# Validate model
result = repo.validate
if result.valid?
  puts "Model is valid"
else
  result.errors.each { |error| puts "ERROR: #{error}" }
end

CLI commands

General

The CLI provides 13 commands organized into 5 categories:

Resource lifecycle:

build - Build LUR packages from XMI/QEA files
info - Show LUR package metadata
validate - Validate LUR packages
validate-qea - Validate QEA files

Viewing:

ls - List elements (packages, classes, diagrams)
inspect - Show element details
tree - Hierarchical package tree
stats - Repository statistics

Querying:

search - Full-text search
find - Criteria-based search

Output:

export - Export to CSV/JSON/Markdown
build-spa - Generate SPA documentation site
serve - Start interactive web UI

Development:

repl - Interactive REPL shell

`build` - Build LUR package

Build a LUR package from XMI or QEA source files.

lutaml uml build MODEL -o OUTPUT.lur [OPTIONS]

Where,

MODEL: Path to XMI or QEA file
-o, --output: Output LUR file path (default: input with .lur extension)
--name: Package name (optional)
--version: Package version (default: 1.0)
--format: Serialization format: marshal or yaml (default: marshal)
--validate: Validate before building (default: true)
--strict: Fail build on validation errors (default: false)

Example 2. Building from XMI file

$ lutaml uml build model.xmi -o model.lur --name "My Model"

Parses the XMI file, validates the model, and creates a LUR package.

Example 3. Building from QEA file

$ lutaml uml build project.qea -o project.lur --validate

Parses QEA directly, faster than XMI export+parse.

Example 4. Build with strict validation

$ lutaml uml build model.xmi --strict

Fails the build if any validation errors are found.

`info` - Show package metadata

Display metadata and statistics for a LUR package without loading the full repository.

lutaml uml info LUR [OPTIONS]

Where,

LUR: Path to LUR package file
--format: Output format: text, yaml, or json (default: text)

Example 5. Viewing package information

$ lutaml uml info model.lur

Shows package name, version, creation date, and contents summary.

`validate` - Validate LUR package

Validate a LUR package for consistency and completeness.

lutaml uml validate LUR [OPTIONS]

Where,

LUR: Path to LUR package file
--verbose: Show detailed per-attribute type resolution information

Checks for:

Dangling references
Missing types (with detailed resolution paths when --verbose is used)
External dependencies
Structural integrity

Example 6. Validating a package

$ lutaml uml validate model.lur

Example 7. Verbose validation with detailed type resolution

$ lutaml uml validate model.lur --verbose

Shows detailed information about type resolution for each attribute, helping diagnose type reference issues.

`validate-qea` - Validate QEA file

Validate QEA file structure, referential integrity, and data quality.

lutaml uml validate-qea FILE [OPTIONS]

Where,

FILE: Path to QEA file
--format: Output format: text or json (default: text)
-o, --output: Save report to file
--strict: Exit with error if validation fails
--show-warnings: Show warnings (default: true)

Example 8. Validating QEA file structure

$ lutaml uml validate-qea model.qea --format json -o report.json

Validates package structure, associations, references, and exports detailed report.

`ls` - List elements

List elements at the specified path in the repository.

lutaml uml ls LUR [PATH] [OPTIONS]

Where,

LUR: Path to LUR package file
PATH: Package path to list (optional, default: root)
--type: Element type: packages, classes, diagrams, or all (default: packages)
--format: Output format: text, table, yaml, or json (default: text)
-r, --recursive: Include nested elements
--lazy: Use lazy loading for large repositories

Example 9. List top-level packages

$ lutaml uml ls model.lur

Example 10. List classes in a package

$ lutaml uml ls model.lur ModelRoot::Core --type classes

Example 11. List all diagrams

$ lutaml uml ls model.lur --type diagrams

`inspect` - Show element details

Display detailed information about a specific element.

lutaml uml inspect LUR ELEMENT [OPTIONS]

Where,

LUR: Path to LUR package file
ELEMENT: Element identifier in format type:identifier

Valid types: package, class, diagram, attribute
--format: Output format: text, yaml, or json (default: text)
--include: Sections to include: attributes, associations, operations

Example 12. Inspect a class

$ lutaml uml inspect model.lur class:Building
$ lutaml uml inspect model.lur class:ModelRoot::Core::Building

Shows class details including attributes, associations, and operations.

Example 13. Inspect a package

$ lutaml uml inspect model.lur package:ModelRoot::Core

Example 14. Inspect a diagram

$ lutaml uml inspect model.lur diagram:ClassDiagram1

`tree` - Show package tree

Display a hierarchical tree view of the package structure.

lutaml uml tree LUR [PATH] [OPTIONS]

Where,

LUR: Path to LUR package file
PATH: Starting package path (optional, default: root)
-d, --depth: Maximum depth to display
--show-counts: Show class and diagram counts (default: true)
--format: Output format: text, yaml, or json (default: text)

Example 15. Show full package tree

$ lutaml uml tree model.lur

Example 16. Show subtree with limited depth

$ lutaml uml tree model.lur ModelRoot::Core --depth 2

`show` - Display element details

General

The show commands display detailed information about specific UML elements.

Showing class details

lutaml uml show class <QUALIFIED_NAME> --from <LUR_PATH>

Example 17. Viewing a class

$ lutaml uml show class "ModelRoot::CityGML2.0::bldg::Building" --from plateau.lur

Displays:

Class name and XMI ID
Stereotype and abstract flag
Inheritance information
Attributes (with types and cardinality)
Associations
Operations

Showing attribute details

lutaml uml show attribute <QUALIFIED_NAME> --from <LUR_PATH>

Where <QUALIFIED_NAME> includes the class path, e.g., Package::Class::attributeName.

Example 18. Viewing an attribute

$ lutaml uml show attribute "ModelRoot::CityGML2.0::bldg::Building::buildingHeight" --from plateau.lur

Displays:

Attribute name
Owning class
Type and cardinality
Visibility and stereotype
Documentation

Showing association details

lutaml uml show association <NAME_OR_ID> --from <LUR_PATH>

Example 19. Viewing an association

$ lutaml uml show association "cityObjectMember" --from plateau.lur

Displays:

Association name and XMI ID
Source and target classes
Roles and multiplicities
Association type

Showing enumeration details

lutaml uml show enum <QUALIFIED_NAME> --from <LUR_PATH>

Example 20. Viewing an enumeration

$ lutaml uml show enum "ModelRoot::Package::StatusCode" --from plateau.lur

Displays:

Enum name and package
All literal values
Stereotypes
Documentation

Showing data type details

lutaml uml show datatype <QUALIFIED_NAME> --from <LUR_PATH>

Example 21. Viewing a data type

$ lutaml uml show datatype "ModelRoot::gml::MeasureType" --from plateau.lur

Displays:

Data type name
Attributes (if structured)
Operations
Stereotypes

Output formats

All show commands support multiple output formats via the --format option:

--format text: Formatted text output (default)
--format yaml: YAML structured data
--format json: JSON structured data

Example 22. Exporting element details as JSON

$ lutaml uml show class "ModelRoot::Package::MyClass" --from model.lur --format json

Returns structured JSON data suitable for programmatic processing.

`stats` - Repository statistics

Display statistics about the repository or a specific package.

lutaml uml stats LUR [OPTIONS]

Where,

LUR: Path to LUR package file
--type: Statistics type: packages, classes, diagrams, or all (default: all)
--detailed: Show detailed breakdown
--format: Output format: text, yaml, or json (default: text)

Example 23. Show repository statistics

$ lutaml uml stats model.lur --detailed

Displays counts of packages, classes, data types, enumerations, diagrams, and stereotypes.

`search` - Full-text search

The search command performs powerful text and pattern-based search across classes, attributes, and associations with advanced filtering, export capabilities, and intelligent suggestions.

Advanced features include wildcard package matching, regex patterns, field-specific search, result export, and search suggestions.

lutaml uml search <LUR> <QUERY> [OPTIONS]

Where,

<LUR>: Path to LUR package file
<QUERY>: Search query text
--type: Element types to search: class, attribute, association (default: all)
--package: Filter by package path (supports wildcards: *, ?, [abc])
--regex: Treat query as regular expression
--in: Fields to search: name, documentation (default: name)
--format: Output format: text, table, yaml, or json (default: table)
--limit: Maximum results (default: 100)

Example 24. Searching for "building" across all element types

$ lutaml uml search plateau.lur "building"

This searches for "building" in class names, attribute names, and association names, displaying results in a table format:

Search Results for 'building':

Type         | Name                    | Package                              | Details
──────────────────────────────────────────────────────────────────────────────────────
Class        | Building                | ModelRoot::CityGML2.0::bldg          | <<FeatureType>>
Class        | BuildingPart            | ModelRoot::CityGML2.0::bldg          | <<FeatureType>>
Attribute    | buildingHeight          | ModelRoot::CityGML2.0::bldg          | Building::buildingHeight : Double
Attribute    | buildingCoverageRate    | ModelRoot::i-UR::urf                 | Administration::buildingCoverageRate : xs::integer
...

Summary: 28 class(es), 73 attribute(s), 45 association(s)

Core search options:

--element-type <TYPE>: Filter results by element type. Valid values: class, attribute, association.
--package <PATH>: Filter results to show only elements within the specified package path. Supports explicit wildcards: *, ?, [abc].
--sort <FIELD>: Sort results. Valid values: type, name, package. Default: type.
--limit <NUMBER>: Limit the number of results displayed. Default: 100.
--format <FORMAT>: Output format. Valid values: table, text, yaml, json. Default: table.
--regex: Treat query as a regular expression pattern. Enables powerful pattern-based searching.
--in <FIELDS…>: Specify which fields to search in. Valid values: name, documentation. Default: name. Can specify multiple fields.
--count: Show only result counts without displaying full results. Displays total count and breakdown by element type.
--export <FILE>: Export search results to a file. Format auto-detected from extension (.json or .yaml/.yml).

Example 25. Wildcard package matching

$ lutaml uml search plateau.lur "building" --package "*i-UR*"

Matches any package path containing "i-UR" anywhere. Found 95 results compared to 50 with full path "ModelRoot::Conceptual Models::i-UR".

Wildcard patterns supported:

* - Matches any characters
? - Matches single character
[abc] - Matches one character from set

Example 26. Regex pattern search

$ lutaml uml search plateau.lur "^Building" --regex --element-type class

Finds all classes whose names start with "Building" (case-sensitive regex). Found 17 classes: Building, BuildingPart, BuildingInstallation, etc.

The --regex flag treats the query as a regular expression:

^Building - Names starting with "Building"
.*Address$ - Names ending with "Address"
Building|Structure - Names containing either word

Example 27. Searching in documentation

$ lutaml uml search plateau.lur "urban planning" --in name documentation

Searches both name and documentation fields. Useful for finding elements by their purpose or description, not just their name.

Multiple fields can be specified:

--in name - Search names only (default)
--in documentation - Search documentation only
--in name documentation - Search both fields

Example 28. Count-only mode

$ lutaml uml search plateau.lur "building" --count

Shows statistics without displaying full results:

Search Results for 'building':

Total Results: 146

Breakdown by Type:
  Association     45
  Attribute       73
  Class           28

Useful for quick analysis or when combined with filters:

$ lutaml uml search plateau.lur "building" --element-type class --count

Example 29. Exporting search results

$ lutaml uml search plateau.lur "Building" --element-type class --export results.json
$ lutaml uml search plateau.lur "Building" --element-type class --export results.yaml

Exports filtered search results to a file for further processing. The format is auto-detected from the file extension.

Exported data includes:

element_type - Type of element (class, attribute, association)
qualified_name - Full qualified name
package_path - Package location
match_field - Which field matched (name or documentation)
match_context - Additional context (e.g., class name for attributes)

Example 30. Search suggestions

When no results are found, the search suggests similar terms based on edit distance and substring matching:

$ lutaml uml search plateau.lur "Buiding"

⚠ No results found for 'Buiding'

Did you mean one of these?
  • Building
  • BuildingPart
  • BuildingInstallation

Suggestions use Levenshtein distance algorithm to find close matches.

Example 31. Combining advanced features

$ lutaml uml search plateau.lur "^Build" \
  --regex \
  --package "*CityGML*" \
  --element-type class \
  --sort name \
  --limit 10 \
  --export citygml_buildings.json

This command:

Uses regex to find names starting with "Build"
Filters to packages containing "CityGML"
Shows only classes
Sorts by name
Limits to 10 results
Exports to JSON file

Multiple filters work together seamlessly.

Example 32. Filtering search results by element type

$ lutaml uml search plateau.lur "building" --element-type class

Shows only classes matching "building", excluding attributes and associations.

Example 33. Searching within a specific package

$ lutaml uml search plateau.lur "urban" --package "ModelRoot::Conceptual Models::i-UR"

Searches for "urban" only within the i-UR package and its subpackages.

Pagination: For large result sets, use pagination to view results in manageable chunks.
--per-page <NUMBER>: Number of results per page. Default: 50.
--page <NUMBER>: Page number to display (1-based). Default: 1.

Example 34. Paginating through search results

$ lutaml uml search plateau.lur "class" --per-page 20 --page 1  # First page
$ lutaml uml search plateau.lur "class" --per-page 20 --page 2  # Second page

View results 20 at a time, navigating through pages.

`find` - Find by criteria

Find elements matching specific criteria.

lutaml uml find LUR [OPTIONS]

Where,

LUR: Path to LUR package file
--stereotype: Filter by stereotype
--package: Filter by package path
--pattern: Match name pattern (regex)
--format: Output format: text, yaml, or json (default: text)

Example 35. Find by stereotype

$ lutaml uml find model.lur --stereotype featureType

Example 36. Find by package

$ lutaml uml find model.lur --package ModelRoot::Core

Example 37. Find by pattern

$ lutaml uml find model.lur --pattern "^Building.*"

`build-spa` - Generate SPA documentation

A LUR package can be transformed into a Single Page Application (SPA) for interactive browsing of the UML model.

The SPA provides a user-friendly web interface with search, navigation, and detailed class views.

Features of the generated SPA:

Vanilla JavaScript: No frameworks required, fast loading
Responsive design: Works on desktop and mobile
Offline capable: Single-file mode works without a server
Search: Full-text search with highlighting
Navigation: Package tree with counts, breadcrumbs
Detailed view: Comprehensive class information with:
- Direct attributes and inherited attributes (in separate tables)
- Direct associations and inherited associations (in separate tables)
- Operations
- Inheritance hierarchy (generalizations and specializations)
- Stereotypes and documentation

Syntax:

lutaml uml build-spa LUR -o OUTPUT [OPTIONS]

Where,

LUR: Path to LUR package file
-o, --output: Output file path (required)
--mode: Generation mode: single_file (default) or multi_file
--title: Documentation title (default: "UML Model Browser")
--theme: Color theme: light (default) or dark

The build-spa command generates an interactive documentation site with:

Search functionality: Full-text search across all model elements
Package navigation: Tree-based browsing of the package hierarchy
Class details: Complete class information including attributes, associations, operations, and inheritance
Inherited data: Separate display of inherited attributes and associations
Diagram integration: Embedded diagram viewing (when available)

Example 38. Generate single-file SPA (default)

$ lutaml uml build-spa model.lur -o docs/index.html --title "My UML Model"

Creates a single HTML file (3-4MB for large models) with all data, CSS, and JavaScript embedded. Perfect for easy distribution and offline viewing.

Example 39. Generate multi-file SPA

$ lutaml uml build-spa model.lur -o docs/ --mode multi_file

Creates a directory structure with separate HTML, CSS, and JavaScript files. Better for version control and incremental updates.

`serve` - Start web UI

Start a web server with an interactive UI for browsing the model.

lutaml uml serve LUR [OPTIONS]

Where,

LUR: Path to LUR package file
-p, --port: Port to listen on (default: 3000)
-h, --host: Host to bind to (default: localhost)

Example 40. Start web UI server

$ lutaml uml serve model.lur --port 8080

Starts interactive web interface at http://localhost:8080.

`repl` - Interactive shell

LutaML provides an interactive command-line shell (REPL) for exploring LUR packages.

Syntax:

lutaml uml repl LUR [OPTIONS]

Where,

LUR: Path to LUR package file
--color: Enable colored output (default: true)
--icons: Enable icons in output (default: true)

Example 41. Start interactive shell

$ lutaml uml repl model.lur

Opens an interactive shell with commands like cd, ls, tree, find, search, bookmarks, and more.

The interactive shell provides a full-featured command-line interface for exploring UML repositories:

# Start interactive shell
lutaml uml shell model.lur

# Inside the shell:
lutaml[/]> help                    # Show available commands
lutaml[/]> ls                      # List packages in current location
lutaml[/]> cd i-UR::urf            # Navigate to package
lutaml[/i-UR::urf]> pwd            # Show current path
lutaml[/i-UR::urf]> tree           # Show tree from current location
lutaml[/i-UR::urf]> find Building  # Find classes
lutaml[/i-UR::urf]> show 1         # Show first search result
lutaml[/i-UR::urf]> bookmark add urf  # Bookmark current location
lutaml[/i-UR::urf]> bm urf         # Jump to bookmark
lutaml[/i-UR::urf]> stats          # Show statistics
lutaml[/i-UR::urf]> exit           # Exit shell

The shell provides a number of useful features:

Tab completion for commands and paths
Command history persisted to ~/.lutaml-xmi-history
Colorized output with Unicode icons
Contextual prompts showing current location
Error handling with helpful messages

Navigation commands

cd PATH

Change to package path

pwd

Print current working path

ls [PATH]

List packages at path

tree [PATH]

Show tree from path

up

Go to parent package

root

Go to ModelRoot

back

Go to previous location

Query commands

find CLASS_NAME

Find class (fuzzy search)

show class QNAME

Show class details

show package PATH

Show package details

show NUMBER

Show numbered result from last search

search QUERY

Full-text search

? QUERY

Alias for search

Bookmark commands

bookmark add NAME

Bookmark current path or last result

bookmark list

List all bookmarks

bookmark go NAME

Jump to bookmark

bookmark rm NAME

Remove bookmark

bm NAME

Quick jump to bookmark

Utility commands

results

Show last search results

export last csv FILE

Export last results to CSV

export last json FILE

Export to JSON

export last yaml FILE

Export to YAML

help [COMMAND]

Show help

history

Show command history

clear

Clear screen

config

Show configuration

stats

Quick statistics

exit, quit, q

Exit shell

Examples

See the examples/ directory for complete examples:

examples/lur_basic_usage.rb - Basic repository operations
examples/lur_cli_workflow.rb - Command-line workflow
examples/lur_statistics.rb - Statistics and validation

Copyright and license

Copyright Ribose. BSD-3 License.

Name		Name	Last commit message	Last commit date
Latest commit History 773 Commits
.github/workflows		.github/workflows
bin		bin
docs		docs
lib		lib
spec		spec
.gitignore		.gitignore
.hound.yml		.hound.yml
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.rubocop_todo.yml		.rubocop_todo.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Gemfile		Gemfile
README.adoc		README.adoc
Rakefile		Rakefile
lutaml.gemspec		lutaml.gemspec
plateau_all_packages.lur		plateau_all_packages.lur

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

LutaML: Unified data model accessor

Purpose

Install

Documentation

Usage

Parsing

Working with UML

General

LutaML UML

Enterprise Architect

Diagram generation

LutaML Diagrams

General

Thin wrapper principle

UML support

QEA Direct Database Parsing

What are QEA files?

Why direct parsing?

Parser API usage

QEA module API

CLI usage with QEA files

File validation

Performance benchmarking

Performance characteristics

Configuration

Limitations

QEA vs XMI Comparison

Performance

Data Richness

Compatibility

LutaML UML Repository (LUR)

General

Package format

Quick start

CLI usage

Build repository from XMI or QEA

Save as LUR package

LUR configuration

General

Search

API reference

Smart loading methods

Error handling with suggestions

Package navigation

Class queries

Inheritance queries

Association & diagram queries

Search and element display

Query DSL (Advanced queries)

Query builder methods

Query examples

Deferred vs immediate execution

Statistics & validation

CLI commands

General

build - Build LUR package

info - Show package metadata

validate - Validate LUR package

validate-qea - Validate QEA file

ls - List elements

inspect - Show element details

tree - Show package tree

show - Display element details

General

Showing class details

Showing attribute details

Showing association details

Showing enumeration details

Showing data type details

Output formats

stats - Repository statistics

search - Full-text search

find - Find by criteria

build-spa - Generate SPA documentation

serve - Start web UI

`build` - Build LUR package

`info` - Show package metadata

`validate` - Validate LUR package

`validate-qea` - Validate QEA file

`ls` - List elements

`inspect` - Show element details

`tree` - Show package tree

`show` - Display element details

`stats` - Repository statistics

`search` - Full-text search

`find` - Find by criteria

`build-spa` - Generate SPA documentation

`serve` - Start web UI

`repl` - Interactive shell