Skip to content

UML Ontology — Design Decisions

Design decisions specific to the UML modeling language ontology. For repo-wide decisions that apply to all Linked.Archi ontologies, see Design Decisions.

UML-DD-1: ODM as Informative Reference (Not Direct Application)

Decision: The OMG Ontology Definition Metamodel (ODM, formal/2014-09-02) is used as an informative reference for mapping principles, not as a directly applied specification. ODM Annex D maps UML model instances (M1) to OWL; Linked.Archi maps the UML metamodel itself (M2) to OWL — a different operation at a different meta-level.

What we take from ODM (structural correspondence, not semantic equivalence):

  • UML metaclasses become owl:Class declarations — but as arch:Element subclasses (palette concepts), not as domain-modeling equivalents of owl:Class
  • UML Generalization hierarchy → rdfs:subClassOf between metaclasses (Annex D.3.3)
  • UML Package → owl:Ontology as namespace (Annex D.3.2)
  • UML Attribute → owl:DatatypeProperty for metaclass features (Annex D.3.4)
  • N-ary Association → owl:Class + properties (Annex D.3.6) — closest precedent for our qualified pattern

The fundamental distinction from ODM:

ODM says: "Your UML model class Course maps to owl:Class rdf:ID="Course"" — UML Class and owl:Class are equivalent constructs for domain modeling.

We say: "The UML metaclass Class is uml:Class a owl:Class ; rdfs:subClassOf arch:Element" — we model UML WITH OWL. Model instances become ex:OrderService a uml:Class, not ex:OrderService a owl:Class.

Where we depart from ODM:

Concern ODM Annex D Linked.Archi Rationale
Meta-level Maps M1 (model instances) Maps M2 (the metamodel) We need metaclasses as types for knowledge graph data
Associations owl:ObjectProperty pair (D.3.5) Three-declaration pattern Architecture needs first-class relationship objects (DD-10)
Enumerations owl:oneOf (D.3.9) SKOS ConceptScheme (may combine with owl:oneOf) Hierarchy, multilingual, extensible (DD-7); owl:oneOf added when closed-enumeration reasoning is needed (see TIME framework)
Multiplicity OWL restrictions (D.3.7) SHACL shapes Closed-world validation (DD-2)
Domain/Range rdfs:domain/rdfs:range (D.3.4) arch:domainIncludes/arch:rangeIncludes Avoids unintended inference (DD-8, guide)
Naming className+propertyName fragments (D.3.1) Standalone IRIs in uml: namespace Simpler, consistent with other Linked.Archi ontologies
Scope One-off transformation per application Reusable shared metamodel The ontology is infrastructure, not a project artifact

Rationale: ODM §8.4.4 explicitly states that "Mappings Are Informative, Not Normative" and that "any particular mapping project will have additional constraints arising from the structure of the particular models to be mapped and the purposes of the project, so will very likely make different mapping choices." Our departures are justified by the architecture knowledge graph use case, which ODM does not address.

Why we still reference ODM: It provides the theoretical foundation — the OMG's own acknowledgment that MOF and OWL are parallel M3 layers and that MOF-based metamodels can be represented in OWL. This validates the entire Linked.Archi approach. The specific mapping rules are a useful starting point even when we depart from them.

UML-DD-2: Selective Metaclass Coverage

Decision: Cover the UML metaclasses that are relevant for architecture modeling in a knowledge graph context. Do not attempt a 1:1 mapping of all ~250 UML metaclasses.

Included (70+ metaclasses): - All concrete classifiers (Class, Interface, Component, DataType, etc.) - All relationship metaclasses (Association, Generalization, Dependency, etc.) - Behavioral elements (Activity, StateMachine, Interaction) - Deployment concepts (Node, Artifact, Device) - Use case concepts (Actor, UseCase) - Key abstract metaclasses that form the hierarchy backbone

Excluded (for now): - Template parameters and bindings (TemplateParameter, TemplateSignature) - Detailed action semantics (ReadStructuralFeatureAction, CreateObjectAction, etc.) - Value specifications (LiteralInteger, LiteralString, Expression, etc.) - UML Diagram Interchange (UML DI) — can be added as a separate module

Rationale: The goal is to enable UML models to participate in the architecture knowledge graph, not to replicate the full UML XMI schema. The included metaclasses cover what architects and developers actually model. The excluded metaclasses are either: - Tool-internal (template bindings, value specifications) - Extremely detailed action semantics (better handled by code analysis tools) - Diagram interchange (a separate concern, following the BPMN DI pattern)

The ontology can be extended incrementally as needs arise.

UML-DD-10: Flat Namespace (Single Ontology File)

Decision: All UML metaclasses live in a single namespace (https://meta.linked.archi/uml/onto#) and a single ontology file (uml-onto.ttl), rather than splitting by UML package (one file per chapter).

Rationale:

  • UML packages (Classes, CommonStructure, StructuredClassifiers, etc.) are organizational, not semantic boundaries — metaclasses freely reference each other across packages
  • A single file is simpler to maintain, validate, and import
  • The BPMN ontology uses a multi-file approach (core, infrastructure, DI) because those are genuinely separate specifications with independent versioning — UML 2.5.1 is a single specification
  • If the ontology grows too large, it can be split later without breaking consumers (the namespace stays the same)

Trade-off: The file is large (~1100 lines). This is acceptable because: - Turtle is human-readable and well-structured with section headers - Tools (Protégé, validators) handle large files without issue - The alternative (10+ small files with circular imports) is worse for maintenance

UML-DD-6: Behavioral Elements as arch:Element (Not Separate Hierarchy)

Decision: Behavioral metaclasses (Activity, StateMachine, Interaction, State, Action, etc.) are aligned to arch:Element via the alignment file, making them first-class nodes in the knowledge graph.

Rationale: In UML, behavioral elements are instances that appear in diagrams and have identity. In the architecture knowledge graph, they need to be: - Queryable (?x a arch:Element finds activities alongside components) - Linkable (an ArchiMate BusinessProcess can be owl:sameAs a UML Activity) - Validatable (SHACL shapes can target them) - Navigable (they appear in viewpoints and taxonomies)

Making them arch:Element subclasses achieves all of this. The alternative — a separate arch:Behavior hierarchy — would fragment the graph and complicate cross-language queries.

UML-DD-7: Activity Edges and Transitions as arch:QualifiedRelationship

Decision: uml:ControlFlow, uml:ObjectFlow, and uml:Transition are aligned to arch:QualifiedRelationship in the alignment file.

Rationale: These are edges in UML diagrams — they connect source and target nodes, carry metadata (guards, effects), and have identity. This maps directly to the arch:QualifiedRelationship pattern:

ex:flow-001 a uml:ControlFlow ;
    arch:source ex:CheckInventory ;
    arch:target ex:ProcessPayment ;
    uml:guard   "[inventory > 0]" ;
.

This enables SPARQL path queries across activity flows and state transitions, and allows SHACL shapes to validate flow connectivity.

UML-DD-8: Generalization Mapped as Both rdfs:subClassOf and Qualified Relationship

Decision: UML Generalization is mapped to both: 1. The uml:generalizes predicate (for direct triple traversal) 2. The uml:Generalization qualified class (for metadata)

It is NOT mapped to rdfs:subClassOf at the M1 (model instance) level.

Rationale: This is a subtle but important distinction:

  • At M2 (the ontology itself), uml:Component rdfs:subClassOf uml:Class — this IS rdfs:subClassOf because it reflects the UML metaclass hierarchy (ODM Annex D.3.3)
  • At M1 (model data), ex:OrderService uml:generalizes ex:BaseService — this is a UML model relationship, NOT an OWL class hierarchy assertion

If we used rdfs:subClassOf at M1, we would be asserting that ex:OrderService is a subclass of ex:BaseService in the OWL sense — which would trigger inference and break the open-world semantics. The UML generalization is a model-level relationship that should be queryable and validatable, not an OWL axiom.

The qualified form (uml:Generalization) allows attaching metadata like isSubstitutable, generalizationSet, and provenance.

UML-DD-9: Sequence Ordering via Integer Index (sequenceNumber)

Decision: The temporal ordering of InteractionFragments in a sequence diagram is represented using an explicit uml:sequenceNumber integer property on each fragment instance, rather than RDF lists (rdf:List), RDF sequences (rdf:Seq), or blank node chains.

Context: In UML 2.5.1, the Interaction::fragment and InteractionOperand::fragment properties are both {ordered} — the position of each InteractionFragment in the collection defines its temporal position in the sequence diagram. In XMI serialisation, this ordering is implicit in the XML document order of <fragment> elements. RDF graphs have no inherent ordering of triples, so an explicit mechanism is needed.

UML also provides GeneralOrdering as a secondary mechanism for expressing partial orders between OccurrenceSpecifications that are not already ordered by the fragment list or by Message send/receive semantics.

Approach:

  1. Primary ordering: uml:sequenceNumber (integer) on each InteractionFragment instance — defines the total order within a single container (Interaction or InteractionOperand)
  2. Secondary ordering: uml:GeneralOrdering instances with uml:orderingBefore and uml:orderingAfter properties — for explicit partial order constraints between OccurrenceSpecifications

Alternatives considered:

Approach Pros Cons
rdf:List Standard RDF mechanism for ordered collections Awkward SPARQL queries (recursive property paths), no random access, insertion requires rewriting the chain
rdf:Seq (rdf:_1, rdf:_2, ...) Simple numbered predicates Deprecated in modern RDF practice, non-standard predicate names
Blank node chains (linked list) Pure RDF Same SPARQL problems as rdf:List, plus blank node identity issues
Integer index Simple ORDER BY ?seq in SPARQL, random access, easy insertion (use gaps like 10, 20, 30), consistent with BPMN pattern Requires renumbering on reorder (mitigated by using gaps)

Rationale:

  • SPARQL ergonomics: ORDER BY ?sequenceNumber is trivial; traversing rdf:List requires recursive property paths (rdf:rest*/rdf:first)
  • Consistency: the BPMN ontology in Linked.Archi uses the same integer-index pattern for SequenceFlow ordering
  • Tooling: graph databases (GraphDB, Stardog, Neptune) optimise integer comparisons; list traversal is expensive
  • Insertion: using gaps (10, 20, 30...) allows inserting new fragments without renumbering existing ones
  • Message ordering is derived: Message M1 precedes M2 if M1.sendEvent.sequenceNumber < M2.sendEvent.sequenceNumber

Example:

# Fragment ordering in a Login sequence diagram
ex:mos1-send a uml:MessageOccurrenceSpecification ;
    uml:covered ex:ll-user ; uml:sequenceNumber 10 .
ex:mos1-recv a uml:MessageOccurrenceSpecification ;
    uml:covered ex:ll-auth ; uml:sequenceNumber 20 .
ex:mos2-send a uml:MessageOccurrenceSpecification ;
    uml:covered ex:ll-auth ; uml:sequenceNumber 30 .
ex:mos2-recv a uml:MessageOccurrenceSpecification ;
    uml:covered ex:ll-db ;   uml:sequenceNumber 40 .

# SPARQL to get messages in order:
# SELECT ?msg ?name WHERE {
#   ?msg a uml:Message ; skos:prefLabel ?name ; uml:sendEvent ?se .
#   ?se uml:sequenceNumber ?seq .
# } ORDER BY ?seq

Relationship to GeneralOrdering:

GeneralOrdering is NOT a replacement for sequenceNumber — it is complementary: - sequenceNumber defines the total order within a container (what XMI document order captures) - GeneralOrdering adds explicit partial-order constraints between specific OccurrenceSpecifications (what the UML spec calls "the ability to define partial orders that may otherwise not have a specified order")

Both mechanisms are needed for full fidelity with the UML 2.5.1 Interactions metamodel.

UML-DD-11: Interaction Metaclass Hierarchy (InteractionFragment as Abstract Base)

Decision: Model InteractionFragment as an abstract base class with OccurrenceSpecification, CombinedFragment, InteractionOperand, InteractionUse, ExecutionSpecification, StateInvariant, and Continuation as concrete subclasses. Model MessageEnd as a separate abstract base with MessageOccurrenceSpecification and Gate as subclasses. MessageOccurrenceSpecification has dual inheritance from both OccurrenceSpecification and MessageEnd.

Rationale: This mirrors the UML 2.5.1 metamodel hierarchy exactly (Chapter 17, ptc-18-01-01.xmi). The dual inheritance of MessageOccurrenceSpecification is the key structural element that connects Messages (via sendEvent/receiveEvent pointing to MessageEnd) to the temporal ordering (via sequenceNumber on OccurrenceSpecification/InteractionFragment).

InteractionFragment (abstract)
├── OccurrenceSpecification
│   └── MessageOccurrenceSpecification ←─── also subClassOf MessageEnd
│       └── DestructionOccurrenceSpecification
├── CombinedFragment
├── InteractionOperand
├── InteractionUse
├── ExecutionSpecification
│   └── BehaviorExecutionSpecification
├── StateInvariant
├── Continuation
└── Interaction (also subClassOf Behavior)

MessageEnd (abstract)
├── MessageOccurrenceSpecification (dual inheritance)
└── Gate

Trade-off: OWL supports multiple inheritance natively (rdfs:subClassOf is not exclusive), so MessageOccurrenceSpecification rdfs:subClassOf :OccurrenceSpecification, :MessageEnd is valid and well-supported by reasoners and SHACL validators.

References