Skip to content

Design Decisions

This document captures the key modeling decisions, rationale, and patterns applied across the Linked.Archi ontologies.

DD-1: Metamodel as Ontology — Architecture Languages in RDF

Decision: Represent architecture metamodels using OWL ontologies and related semantic web resources rather than UML profiles, XML schemas, or custom formats.

Rationale: An architecture metamodel can be expressed as the abstract syntax of a domain-specific modelling language. A metamodel defines the language for expressing a model — it provides the types, relationships, and constraints for a modelling language within a particular domain. Representing it in RDF lets us assign each layer of the language to the formalism suited to it:

  • OWL — formal semantics for the core concepts and their logical relationships (the meta-language for defining them)
  • SKOS — controlled vocabularies and taxonomies for classifying and organising architecture elements
  • SHACL — structural validation and governance constraints (closed-world)
  • SPARQL — standard query language for traversing the resulting graph

The result is a single integrated graph offering machine-interpretable precision, vocabulary-level interoperability, SPARQL queryability, and the ability to generate stakeholder-specific views from one source of truth.

Trade-off: Higher learning curve for teams unfamiliar with semantic web technologies. Mitigated by the minimal OWL profile (DD-2) and comprehensive documentation.

DD-2: Minimal OWL Profile with SHACL Constraints

Decision: Use only a small subset of OWL for vocabulary semantics, and delegate all closed-world constraints to SHACL.

Rationale: The most common modeling failure mode is treating OWL axioms as if they were closed-world constraints. OWL operates under the Open World Assumption — the absence of a statement does not mean it is false. SHACL provides the closed-world validation that governance requires.

What OWL handles:

  • Class and property declarations
  • Simple hierarchies (rdfs:subClassOf, rdfs:subPropertyOf)
  • Property typing (owl:ObjectProperty vs owl:DatatypeProperty)
  • Modularization (owl:imports)
  • Documentation metadata

Retained inference — a short, deliberate list where the entailment is wanted:

  • Subsumption (rdfs:subClassOf/rdfs:subPropertyOf) — relied upon by SHACL shapes (which target superclasses) and by query generalization
  • Transitivity on compositional properties (hasPart/partOf) — part-of chains resolve automatically
  • Inverse pairs (e.g. hasPart/partOf) — bidirectional traversal without asserting both triples
  • Functionality where a property is single-valued (e.g. prefVisNotation)
  • owl:sameAs — admitted only as a documented exception for confirmed cross-source identity merges (see DD-11, identity correspondence vs. merge); the default cross-source link is the non-inferential skos:exactMatch

Everything else — cardinality, disjointness, value restrictions, equivalence used as constraint — is expressed in SHACL, not OWL.

What SHACL handles:

  • Cardinalities (sh:minCount, sh:maxCount)
  • Required properties
  • Value constraints (sh:datatype, sh:class, sh:pattern, sh:in)
  • Closed shapes
  • Cross-field and conditional rules

Why not RDFS-only: Keeping minimal OWL buys property typing that tools understand (WIDOCO, WebVOWL), better documentation generation, and a smoother Protégé authoring workflow.

Clarification — Is this still an ontology, or just a schema?

Minimising OWL raises a fair question: if constraints live in SHACL and only a thin layer of OWL remains, is the result still an ontology, or has it become a schema? The answer is that it remains an ontology, and the question conflates two separable ideas bundled under the word "ontology":

  1. Shared, explicit conceptualisation with formal identity. Concepts have globally-resolvable IRIs, explicit definitions, and a vocabulary other modules import and extend — so a bs:Component means the same thing wherever it appears. A schema (XSD, DDL, JSON Schema) defines the shape of valid documents within one system; it is local and closed, and its meaning does not travel. Linked.Archi has the former property throughout.
  2. A subsumption/classification structure with inference. The ontologies carry an is-a hierarchy over which subsumption is computed and relied upon (see the retained-inference list above). A schema has no notion of "every X is automatically a Y." Linked.Archi keeps this.
  3. Rich logical (DL) axiomatisation — restrictions, disjointness, cardinality-as-entailment, property chains. This is what the minimal profile deliberately declines.

Linked.Archi builds ontologies in senses (1) and (2) while declining most of (3). That is not "an ontology degraded into a schema" — it is a lightly-axiomatized ontology that relocates constraints rather than removing them. A schema's defining job is to constrain structure; those constraints are fully present here, expressed in SHACL — the layer designed for the closed-world validation that governance requires and that OWL's open-world axioms handle badly. (SHACL exists precisely because OWL was being misused as a schema language.)

So the division of labour is: OWL/RDFS carries meaning, identity, and classification — what ontologies are uniquely good at; SHACL carries constraint and validation — what schemas are good at. Calling the result "just a schema" mistakes the validation layer for the whole artifact. (DD-5 makes the complementary point structurally: RDFS+OWL sits at the M3 layer — the layer that defines ontologies — so the substrate is ontological by construction.)

The concession. Declining DL axiomatization does give up automated consistency checking and rich DL inference (necessary-and-sufficient classification, disjointness-based contradiction detection, property-chain entailment). The inference Linked.Archi relies on is the bounded list above — subsumption plus a few property characteristics — not full DL reasoning. Inference claims elsewhere in the documentation should stay within that boundary.

DD-3: ISO 42010 Alignment for Core Concepts

Decision: Align core ontology concepts with ISO/IEC/IEEE 42010 (Architecture Description).

Rationale: ISO 42010 provides a well-established conceptual framework for architecture description that is framework-agnostic. By aligning with it:

  • The core ontology is not biased toward any specific EA framework
  • Concepts like System, Architecture, Model, Viewpoint, View, Stakeholder, and Concern have precise, standardized meanings
  • The distinction between Architecture (abstract, inherent to a system) and Architecture Description (work product) is preserved
  • Multiple frameworks (TOGAF, DoDAF, Zachman, ADMIT) can be mapped to the same foundation

Core aligns with ISO 42010 as its conceptual basis and deliberately does not ground in a foundational (upper) ontology — see DD-4 for that decision and the alternatives considered.

DD-4: No Foundational Ontology — Lightweight Domain Core Instead

Decision: Do not ground arch:core in a foundational (upper) ontology such as BFO, DOLCE, UFO, or GIST. Instead, arch:core is a lightweight domain core ontology for enterprise architecture, aligned with ISO/IEC/IEEE 42010 (DD-3) and neutral across EA frameworks. Core plays the upper-ontology role, but concretely it is a domain reference ontology (or "core ontology" / "foundational layer") within the Linked.Archi hierarchy (everything imports it; nothing domain-specific lives in it) without being a foundational ontology in the BFO/DOLCE sense.

Rationale:

  • Consistency with the minimal-OWL profile (DD-2). Foundational ontologies — especially BFO and DOLCE — are heavily axiomatized in OWL-DL (disjointness, restrictions, the constraint-style axioms DD-2 deliberately declines). Importing one and then running a minimal-OWL/SHACL profile is self-defeating: either we pull in axioms we have chosen not to use, or we import the ontology and ignore its axioms, which forfeits the rigor that was the point of grounding.
  • Accessibility. A core premise of the project is lowering barriers to adoption. Requiring foundational-ontology literacy to extend a module contradicts that goal.
  • Open- vs closed-world. Foundational ontologies assume open-world DL reasoning; Linked.Archi validates closed-world via SHACL (DD-2). Grounding in a DL-heavy foundation reintroduces the OWA mismatch the profile exists to avoid.
  • EA-framework neutrality, not category neutrality. Core needs to be neutral across ArchiMate, TOGAF, Zachman, etc. — a domain neutrality. It does not need to be neutral across all categories of existence (endurant/perdurant, object/process), which is what a foundational ontology provides and what EA modelling does not require.
  • Practitioner expectation. No ArchiMate or TOGAF practitioner models against BFO. Grounding there optimizes for the academic-ontology audience at the expense of the practitioner audience the project targets.

Alternatives considered:

Foundational ontology Why not adopted as the grounding
BFO Heavily axiomatized OWL-DL; realist endurant/occurrent commitments; conflicts directly with the minimal-OWL profile and the accessibility goal.
DOLCE Rich descriptive/cognitive axiomatization; same DL-weight and learning-curve objections as BFO.
UFO The most relevant — UFO has been used to analyze and repair ArchiMate's semantic ambiguities (see companion note). Its analyses inform our concept definitions, but importing UFO axiomatically reintroduces DL weight and OWA reasoning we have declined.
GIST The closest genuine alternative — Semantic Arts' minimalist upper ontology for the enterprise (~100 classes/properties), using everyday business concepts rather than philosophical primitives. It is minimalist in concept count, but it is still DL-axiomatized: it uses fine-grained disjointness at the top level so a reasoner detects inconsistency. Two reasons we did not build on it: (a) that disjointness-based DL reasoning is exactly the constraint-style OWL the minimal profile declines (DD-2); (b) grounding EA notations in GIST's generic primitives pulls toward GIST's reduce-to-essentials philosophy, which is in tension with our notation-fidelity goal (we preserve each notation's specific standardized types, not collapse them). ISO 42010 was preferred as the anchor because it is an architecture-description standard at our actual layer (DD-3). GIST's minimalism nonetheless validates the lightweight approach core takes.

Consequences:

  • We forgo principled interoperability with other foundationally-grounded ontologies (e.g. BFO-based biomedical ontologies) and the automated consistency-checking a DL-rich foundation enables. This is accepted: those benefits serve cross-domain academic interoperability, not the EA-practitioner use case.
  • Core's category choices are justified by ISO 42010 and EA practice rather than by a foundational ontology. Where finer ontological distinctions matter, UFO-based analyses inform definitions without being imported (see companion note).
  • "Upper ontology" is reserved for its technical meaning; core is described as the foundational layer / domain core, never as "an upper ontology," to avoid the category claim it does not make.

References:

DD-5: MOF↔OWL Equivalence — Why RDF Can Represent Any MOF-Based Modeling Language

Decision: Linked.Archi treats RDFS+OWL as the M3 (meta-metamodel) layer, functionally equivalent to OMG's Meta Object Facility (MOF). Any MOF-based modeling language (UML, BPMN, SysML, etc.) can be faithfully represented as an OWL ontology. The OMG Ontology Definition Metamodel (ODM, formal/2014-09-02) provides the formal mapping rules.

Context — The Four-Layer Architecture:

Both the OMG and W3C stacks use a four-layer metamodel architecture:

Layer   OMG Stack                    W3C Semantic Web Stack
─────   ─────────                    ──────────────────────
M3      MOF                          RDFS + OWL
        (defines metamodels)         (defines ontologies)

M2      UML, BPMN, SysML, OWL        OWL ontology (e.g., uml-onto.ttl)
        (all defined using MOF)      (defined using OWL classes/properties)

M1      UML model instances          RDF individuals
        (conform to M2)             (typed with M2 classes)

M0      The real world               The real world

In Linked.Archi, RDFS/OWL is the foundational layer. Modeling languages like UML, BPMN, and ArchiMate are expressed as OWL ontologies (M2), and model instances are RDF individuals typed with those classes (M1). The OMG four-layer framing is used for didactic continuity with OMG-trained colleagues — structurally, the W3C stack is flatter because RDFS is reflective (rdfs:Class rdf:type rdfs:Class) and does not require a separate meta-meta tier.

The ODM Mapping Rules:

The OMG Ontology Definition Metamodel (ODM) defines the formal correspondence between MOF and OWL constructs:

MOF Construct (M3) OWL/RDFS Construct (M3) ODM Reference Notes
UML::Package owl:Ontology Annex D.3.2 Namespace and modularization
UML::Class owl:Class Annex D.3.3 Direct correspondence
UML::Generalization rdfs:subClassOf Annex D.3.3 Direct correspondence
UML::Property (attribute) owl:DatatypeProperty Annex D.3.4 Structural features of classifiers
UML::Property (reference) owl:ObjectProperty Annex D.3.4 Navigation between classifiers
UML::Association (binary) owl:ObjectProperty Annex D.3.5 Binary associations map to property pairs
UML::AssociationClass owl:Class + functional properties Annex D.3.6 N-ary associations become classes
UML::Multiplicity owl:minCardinality / owl:maxCardinality Annex D.3.7 Cardinality restrictions
UML::Enumeration owl:oneOf or SKOS Annex D.3.9 Linked.Archi uses SKOS (DD-7)

Where MOF and OWL/SHACL Diverge:

Concern MOF OWL/RDFS Linked.Archi Resolution
World assumption Closed — what's not stated is false Open — absence of a statement is not denial SHACL provides closed-world validation (DD-2)
Associations First-class binary constructs with named ends, navigability, multiplicity Properties — simpler, no named ends Three-declaration qualified relationship pattern (DD-10)
Constraints Built-in (multiplicity, ordered, unique) No built-in constraints SHACL shapes (DD-2)
Reflexivity MOF is defined in terms of itself RDFS is reflexive; OWL avoids it for decidability Not relevant for Linked.Archi's minimal OWL profile
Serialization XMI (XML-based) RDF (Turtle, JSON-LD, N-Triples) Turtle as primary format

_ In Linked.Archi we use SHACL shapes for constraints (DD-2) _

Why This Matters for Linked.Archi:

This equivalence is the theoretical foundation for the entire project. Because OWL sits at the same M3 layer as MOF:

  1. Any MOF-based modeling language (UML, BPMN, SysML, CWM) can be represented as an OWL ontology
  2. Models conforming to those languages become RDF individuals — queryable, linkable, validatable
  3. Multiple modeling languages can coexist in the same knowledge graph because they share the same M3 substrate
  4. Cross-language queries are possible because all models are RDF triples regardless of their source language

This is not a theoretical claim — it is demonstrated by the BPMN ontology (derived from OMG XMI/CMOF), the UML ontology (following ODM mapping rules), and the ArchiMate ontology (mapped from the Open Group specification).

References:

DD-6: No Punning — OWL Classes and SKOS Taxonomies Stay Separate

Decision: Do not use OWL 2 punning (same IRI as both class and individual, or class and property). Use OWL class hierarchies for formal semantics and SKOS concept schemes for lightweight classification, linked via annotation properties.

Rationale: Punning is tempting in enterprise architecture because ArchiMate involves element types (meta-level) and model elements (instance-level), plus cross-cutting classifications (active/passive, internal/external, layers). Reusing the same IRI for multiple roles seems convenient but creates predictable problems:

  • Under OWL 2 Direct Semantics, punned views are interpreted independently — no logical bridge exists between them. Modelers expect cross-level entailments that do not happen.
  • Mainstream tools (Protégé, visualization tools, SPARQL endpoints) handle punning inconsistently — duplicate UI entries, broken annotation display, ambiguous query results.
  • Integration across heterogeneous stacks (RDFS inferencing, SHACL validation, rule engines, partial OWL RL) amplifies semantic mismatches.
  • SPARQL under OWL Direct Semantics entailment requires variable typing that makes meta-queries awkward or illegal.

The Linked.Archi approach instead:

  • OWL class hierarchies for formal semantics that reasoners understand (e.g., arch:ActiveStructureElement rdfs:subClassOf arch:Element — so instances inherit the classification)
  • SKOS concept schemes for lightweight faceted classification (by layer, aspect, exposure) linked to OWL classes via owl:AnnotationProperty — queryable in SPARQL, ignored by DL reasoners
  • No same-IRI reuse across entity categories — separate namespaces/patterns for classes, properties, individuals, and taxonomy concepts

This follows the OWL 2 specification's own guidance: use annotations when information should not contribute to logical consequences.

Clarification — SKOS annotation properties on OWL classes:

Using skos:prefLabel, skos:definition, skos:altLabel, and skos:scopeNote on owl:Class declarations is explicitly permitted and does NOT constitute punning. These properties are typed as owl:AnnotationProperty in the SKOS OWL vocabulary — they attach lexical metadata to any resource without altering its logical role. An owl:Class carrying a skos:prefLabel does not become a skos:Concept.

Clarification — Taxonomy skos:narrower pointing at OWL class IRIs:

The taxonomy files (e.g., archimate3.2-tax.ttl) use skos:narrower to reference OWL class IRIs directly as leaf nodes:

:BusinessLayer
    a             skos:Concept ;
    skos:narrower am:BusinessActor, am:BusinessRole, am:BusinessProcess . . . .

Under strict RDFS entailment, skos:narrower has rdfs:range skos:Concept — so this would infer am:BusinessActor rdf:type skos:Concept, creating implicit class-individual punning. Linked.Archi accepts this pragmatically because:

  1. No RDFS materialization is run on taxonomy files — the entailment regime is minimal OWL (DD-2), not RDFS closure. The rdf:type skos:Concept triple is never materialized.
  2. The purpose is tool consumption — modeling tools read skos:narrower to populate palettes and navigation trees. They do not run RDFS inference on the taxonomy.
  3. rdfs:seeAlso is the explicit bridge — each SKOS grouping concept (e.g., amtax:BusinessLayer) carries rdfs:seeAlso am:BusinessLayerElement to link the navigational concept to its OWL class counterpart without range-based entailment.
  4. OWL 2 Direct Semantics treats annotation assertions independently — even if a tool loads both files, the class and individual interpretations remain in separate semantic domains under Direct Semantics.

The leaf-level skos:narrower references are a pragmatic shortcut for tool interoperability. If strict RDFS-entailment environments are targeted, replace direct class references with dedicated skos:Concept individuals per leaf and link them to the OWL class via rdfs:seeAlso.

What remains prohibited:

  • Explicitly declaring am:BusinessProcess a owl:Class, skos:Concept — this is intentional punning
  • Using the same IRI as both owl:ObjectProperty and owl:Class
  • Relying on cross-category entailments that depend on punned interpretations being logically connected

References:

DD-7: SKOS for Taxonomies and Classification

Decision: Use SKOS concept schemes for classifying model concepts rather than OWL class hierarchies.

Rationale: SKOS provides:

  • Multiple independent classification dimensions (by layer, by aspect, by domain) without multiple inheritance issues
  • Navigation aids for modeling tools (palette generation, filtering)
  • Controlled vocabularies with preferred/alternative labels
  • Broader/narrower relationships that are explicitly navigational, not ontological

The ArchiMate taxonomy, for example, classifies elements both by layer (Business, Application, Technology) and by aspect (Active Structure, Passive Structure, Behavior) — two orthogonal dimensions that would be awkward to model as OWL class hierarchies.

DD-8: domainIncludes / rangeIncludes Instead of rdfs:domain / rdfs:range

Decision: Use arch:domainIncludes and arch:rangeIncludes (modeled after schema:domainIncludes) for relationship guidance, reserving rdfs:domain/rdfs:range for cases where inference is genuinely desired.

Rationale: In RDFS/OWL, rdfs:domain and rdfs:range are inference axioms, not constraints. Stating rdfs:domain :Node on a property means "anything that uses this property is inferred to be a :Node" — which is often not the intended behaviour.

arch:domainIncludes / arch:rangeIncludes serve as guidance for modeling tools (e.g., relationship wizards that propose valid connections) without triggering unintended inference. Actual constraints are implemented in SHACL.

Relationship to SHACL: SHACL does not read rdfs:domain, rdfs:range, arch:domainIncludes, or arch:rangeIncludes — it defines its own constraints independently via sh:class, sh:targetClass, and sh:node. However, the interaction between entailment and SHACL is real and must be understood:

Mechanism Layer Effect
rdfs:domain / rdfs:range RDFS inference Infers type — "anything using this property IS a X" (open world)
arch:domainIncludes / arch:rangeIncludes Annotation Suggests valid types — for tooling hints, documentation, relationship wizards
sh:class, sh:targetClass, sh:node SHACL validation Validates — "if this property is used, the value MUST be a X" (closed world)

SHACL shapes declare their own sh:class and sh:targetClass directly — they are the enforcement layer. The arch:domainIncludes/arch:rangeIncludes annotations are the documentation and tooling layer. Neither depends on the other at runtime.

The entailment interaction: While SHACL itself does not read domain/range declarations, SHACL operates on whatever graph it receives — including materialized inferences. If RDFS entailment runs before SHACL validation (as it does in engines like GraphDB or Stardog with reasoning enabled), the materialized triples affect which shapes fire:

  • rdfs:subClassOf transitivity means a shape targeting am:ActiveStructureElement fires on am:BusinessActor instances — this is desired behaviour and is the reason Linked.Archi uses class hierarchies for aspect/layer classification (see AM-DD-1).
  • rdfs:domain/rdfs:range inference would cause undesired behaviour: any resource using a property with rdfs:domain :Node would be inferred as :Node, causing shapes targeting :Node to fire on unexpected instances.

This is the key distinction: rdfs:subClassOf entailment is intentional and relied upon by SHACL shapes (they use rdf:type/rdfs:subClassOf* property paths). Domain/range entailment is unintentional and would pollute the type graph. By using annotation properties (arch:domainIncludes/arch:rangeIncludes) instead of rdfs:domain/rdfs:range, the type graph remains clean — only explicit rdf:type assertions and rdfs:subClassOf inheritance determine which shapes apply to which instances.

For a deeper treatment with examples, trade-off analysis, and practical implications for SPARQL and validation pipelines, see the Domain & Range Guide.

DD-9: ModelConcept as Base Class (Not Direct Use of owl:Class)

Decision: Introduce arch:ModelConcept as the base class for all architecture model concepts rather than using owl:Class or rdfs:Resource directly.

Rationale: Architecture model concepts need to:

  • Be presented in different contexts with specific visual notations
  • Be understood correctly by stakeholders (not just machines)
  • Be available in a modeling palette for architects to use
  • Have restrictions defined by the architecture framework
  • Carry governance metadata (ownership, master data source)

These requirements are specific to architecture modeling and would be lost if using generic RDF/OWL constructs directly. ModelConcept provides the semantic anchor for all of this.

DD-10: Clean Separation of Predicates and Relationship Resources

Decision: Relationship types are standard owl:ObjectProperty declarations. Relationship occurrences that need identity, metadata, or lifecycle management are instances of arch:QualifiedRelationship subclasses. The two are bridged by arch:unqualifiedForm (schema-level mapping) and rdf:reifies (RDF 1.2 instance-level bridge).

Rationale: Architecture models need two views of every relationship:

  1. A direct predicate for graph traversal — ex:AppSvc1 am:serves ex:BizProc1 — enabling SPARQL property paths, reasoning, impact analysis, and simple queries
  2. A first-class resource for architecture management — a QualifiedRelationship instance carrying provenance, confidence, lifecycle state, view context, approval status, and supporting multiplicity (multiple distinct edges between the same pair)

Earlier iterations of the core ontology used a metaclass pattern (arch:Relationship rdfs:subClassOf rdf:Property) and OWL 2 punning to make relationship types serve both roles simultaneously. The current design moves away from this: relationship types are plain owl:ObjectProperty, and the qualified form is a separate class hierarchy under arch:QualifiedRelationship.

Three complementary representations are emitted for every relationship:

  1. Direct triple — source vocab:serves target — for SPARQL traversal
  2. Qualified predicate — source vocab:qualifiedServes relationshipNode — for navigation to the full resource
  3. Qualified relationship resource — carries all metadata: labels, provenance, lifecycle, etc.
  4. rdf:reifies — bridges the direct triple to the resource (RDF 1.2)

This separation is cleaner because:

  • Relationship types as standard owl:ObjectProperty work consistently across all reasoners and tools — no punning edge cases
  • Qualified relationship resources are genuine architectural objects, not reification workarounds — they can be the source or target of other relationships (higher-order modeling)
  • The schema mapping (arch:unqualifiedForm) is explicit and validatable via SHACL
  • RDF 1.2 rdf:reifies provides the standardized bridge, replacing the older rdf:Statement-based approach
  • Multiple distinct reifiers for the same proposition are supported — essential when the same logical relation appears in different contexts (current vs target state, observed vs inferred)

The pattern adopts and extends the PROV-O qualified relation pattern:

PROV-O Linked.Archi Role
prov:EntityInfluence arch:QualifiedRelationship Base class for qualified nodes
prov:influencer / prov:entity arch:source / arch:target Source and target elements
prov:unqualifiedForm arch:unqualifiedForm Schema-level mapping
prov:qualifiedInfluence Type-specific qualified property Navigates source → qualified node
(no equivalent) rdf:reifies (RDF 1.2) Bridges direct triple to resource

Anti-patterns to avoid:

  • Do not treat relationship occurrences as predicates — relationship type is a predicate, relationship occurrence is a resource
  • Do not use arch:unqualifiedForm on instance data — it is a schema-level mapping
  • Always emit the unqualified triple alongside the qualified resource — consumers doing analytics need the direct predicate

References:

DD-11: Identity Mechanism — Correspondence vs. Merge

Decision: Use skos:exactMatch as the default mechanism for cross-source correspondence. Reserve owl:sameAs for a documented subset of cases where the two IRIs are confirmed to be the same individual and a full property merge is wanted. Record which mechanism was used, and why, in the reconciliation graph's provenance.

Context: When the same real-world system appears in two sources (e.g. a Backstage bs:Component and an ArchiMate am4:ApplicationComponent), the graph needs a way to relate the two nodes so cross-source queries can span them. Two RDF mechanisms are available, and they make different claims.

Rationale:

  • skos:exactMatch asserts interchangeability for retrieval/mapping without asserting logical identity. It carries no OWL entailment, so the everyday query path stays reasoner-free (consistent with the minimal-OWL profile, DD-2); the linked nodes keep their native types; and the link is revocable without touching source data.
  • owl:sameAs asserts the nodes are one individual and triggers a complete, bidirectional property merge under reasoning. It is powerful where genuine identity holds, but unforgiving — a wrong sameAs silently corrupts all downstream queries — and it pulls OWL entailment into the common path.
  • Decision rule (substitutability): if a reasoner could safely replace one IRI with the other everywhere, forever, the nodes are one entity → owl:sameAs. Otherwise → skos:exactMatch. Most EA cross-source links fail the substitutability test, because notations model the same system at different granularities and concerns, so correspondence is the right default and merge the exception.

Consequences:

  • Cross-source queries traverse skos:exactMatch explicitly (one extra hop); they do not get an automatic property pool. This is accepted as the cost of keeping the link inspectable and inference-free.
  • The two mechanisms must not be mixed silently: a query written for one will miss links made with the other. Hence one default per deployment (skos:exactMatch), with owl:sameAs confined to a recorded subset.
  • Identity decisions are authored and reviewed, never inferred by converters (see the reconciliation method in Bridging Architecture Silos).

DD-12: Versioned Namespace IRIs

Decision: Include version numbers in ontology namespace IRIs (e.g., https://meta.linked.archi/core#).

Rationale: Enables:

  • Multiple versions to coexist in the same triplestore
  • Explicit owl:imports of specific versions
  • Clear provenance tracking
  • Backward compatibility management via owl:priorVersion

DD-13: Metamodel as Manifest (Separate from Ontology)

Decision: A Metamodel (arch:Metamodel) is a separate resource from the ontology that defines model concepts. The metamodel is a manifest that aggregates all constituent resources — the model concepts ontology, SHACL shapes, derivation rules, viewpoints, taxonomy, deliverable templates, reference data, reference models, and presentation contexts — via composition properties.

Rationale: A modeling language is more than just an ontology of elements and relationships. It includes validation rules (SHACL), derivation rules, viewpoint definitions, taxonomies (SKOS), deliverable templates, reference data, and presentation contexts. These are separate concerns maintained in separate files.

The metamodel manifest provides:

  • A single entry point for tools to discover all resources that make up a modeling language
  • Clean separation of concerns — each file has one job
  • Independent versioning and maintenance of each resource
  • The ability for simple metamodels to be just an ontology (the ontology can type itself as arch:Metamodel) while complex ones use a separate manifest

Pattern:

# The manifest (archimate3.2-metamodel.ttl)
ammm:ArchiMate3.2
    a                              arch:Metamodel ;
    arch:basedOnFramework          ammm:ArchiMateFramework ;
    arch:modelConcepts             <https://meta.linked.archi/archimate3/onto#> ;
    arch:formalRules               amsh:, amelsh:, ampsh: ;
    arch:derivationRules           amderiv: ;
    arch:architectureViewpoints    amvp: ;
    arch:conceptClassification     <https://meta.linked.archi/archimate3/tax#> ;
    arch:viewpointLibrary          amvp:ViewpointCatalog ;
    arch:hasDeliverableTemplate    ammm:ArchitectureDefinitionDocument ;
    arch:referenceData             ammm:ArchiMateReferenceData ;
    arch:referenceModels           ammm:ArchiMateReferenceModels ;
    arch:presentationContextScheme ammm:ArchiMatePresentationContexts .

# A model conforms to the metamodel
ex:MyModel
    a                             arch:Model ;
    arch:modelConformsToMetamodel ammm:ArchiMate3.2 ;
    arch:deliverableTemplateUsed  ammm:ArchitectureDefinitionDocument .

For simple metamodels (e.g., Backstage, C4), the ontology can still type itself as arch:Metamodel directly — no separate manifest needed. The manifest pattern is for when the metamodel aggregates multiple files.

References:

  • ArchiMate 3.2 metamodel: modelingLanguages/archimate/3.2/archimate3.2-metamodel.ttl (reference implementation)

DD-14: Default Namespace Prefix and Ontology Header Convention

Decision: Every Linked.Archi ontology file declares @prefix : pointing to its own namespace IRI, and includes a standard header block with vann:preferredNamespaceUri, vann:preferredNamespacePrefix, owl:versionIRI, and owl:imports.

Pattern:

@prefix :        <https://meta.linked.archi/{name}#> .
@prefix arch:    <https://meta.linked.archi/core#> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix vann:    <http://purl.org/vocab/vann/> .
@prefix dc:      <http://purl.org/dc/elements/1.1/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix cc:      <http://creativecommons.org/ns#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .

<https://meta.linked.archi/{name}#>
    a                             owl:Ontology ;
    owl:imports                   <https://meta.linked.archi/core#> ;
    cc:license                    "http://creativecommons.org/licenses/by/4.0/" ;
    vann:preferredNamespaceUri    "https://meta.linked.archi/{name}#" ;
    vann:preferredNamespacePrefix "{prefix}" ;
    dc:title                      "..."@en ;
    dc:description                "..."@en ;
    dcterms:created               "YYYY-MM-DD"^^xsd:date ;
    dcterms:modified              "YYYY-MM-DD"^^xsd:date ;
    dc:publisher                  "Linked.Archi"@en, <https://linked.archi> ;
    owl:versionIRI                <https://meta.linked.archi/{name}/{version}#> ;
    owl:versionInfo               "{version}"@en ;
.

Rationale:

  1. @prefix : — The default namespace prefix enables concise element declarations (:BusinessActor instead of am:BusinessActor within the file). It also serves as the canonical signal for tooling (WIDOCO, the build script, Protégé) to identify the ontology's own namespace.

  2. vann:preferredNamespaceUri + vann:preferredNamespacePrefix — Machine-readable namespace metadata. Used by documentation generators, prefix registries, and the build pipeline as a fallback when @prefix : is not present.

  3. owl:imports — Explicit dependency declaration. Every modeling language and extension imports arch:core. Tools can resolve the full dependency chain.

  4. Standard metadata — dc:title, dc:description, dcterms:created, dcterms:modified, cc:license, dc:publisher, owl:versionIRI, owl:versionInfo ensure every ontology is self-describing and discoverable.

Consistency rule: All ontology files (*-onto.ttl) in core/, extensions/, modelingLanguages/, and frameworks/ must follow this convention. Files that don't (e.g., BPMN sub-ontologies, legacy TOGAF/Zachman files) should be updated to conform.

Tooling dependency: The doc generator (.scripts/.tools/generate-docs.sh) extracts the ontology name from @prefix : to determine the output directory. Ontologies without this declaration are skipped. The fallback reads vann:preferredNamespaceUri.

DD-15: Three-Graph Architecture for ETL

Decision: Converters produce three named graphs: semantic, views, and provenance.

Rationale:

  • Semantic graph — Core architectural elements and relationships (the knowledge)
  • Views graph — Diagram layout and visualization data (the presentation)
  • Provenance graph — Conversion metadata and lineage (the governance)

This separation allows consumers to load only what they need (e.g., skip diagram data for pure analysis), maintains clear data lineage, and follows the PROV-O provenance model.

DD-16: Source Attribution and Provenance — dcterms:source + prov:wasDerivedFrom

Decision: Use both dcterms:source and prov:wasDerivedFrom (or prov:hadPrimarySource) on ontology headers to declare derivation sources. They are complementary, not competing. Use dcterms:source consistently everywhere — never the legacy dc:source.

Rationale: The two properties solve overlapping but distinct problems:

  • dcterms:source is a flat, bibliographic statement: "this resource is derived from that one." It's what tooling ( Protégé, LOV, WIDOCO) picks up and displays as "sources." No commitment to a process model — no agents, activities, or timestamps. Use on both ontology headers AND individual OWL classes (to link each entity to its spec section).

  • prov:wasDerivedFrom is part of PROV-O's derivation chain. It says the same thing semantically ("entity B was generated from entity A") but plugs into a richer graph: you can attach a prov:Activity (the act of generating the ontology), a prov:Agent (the author or tool), prov:generatedAtTime, etc. If you ever need to answer "how, when, and by whom was this ontology produced from source X?", prov:wasDerivedFrom is the anchor.

  • prov:hadPrimarySource (subproperty of prov:wasDerivedFrom) is specifically meant for "the original document this content traces back to." Specifications (TOGAF, ArchiMate, BPMN, UML) and foundational research (Kotusev's books/papers) are textbook primary sources.

Pattern:

<my-ontology>
    a                     owl:Ontology ;
    dcterms:source        <https://pubs.opengroup.org/togaf-standard/architecture-content/chap02.html> ;
    prov:wasDerivedFrom   <https://pubs.opengroup.org/togaf-standard/architecture-content/chap02.html> ;
    prov:hadPrimarySource <https://pubs.opengroup.org/togaf-standard/architecture-content/chap02.html> ;
.

For book-form sources without stable URIs, mint source entities typed as bibo:Book and prov:Entity:

@prefix bibo:    <http://purl.org/ontology/bibo/> .
@prefix prov:    <http://www.w3.org/ns/prov#> .
@prefix dcterms: <http://purl.org/dc/terms/> .

<my-ontology>
    a                   owl:Ontology ;
    dcterms:source      :AuthorYear ;
    prov:wasDerivedFrom :AuthorYear ;
.

:AuthorYear
    a                 bibo:Book, prov:Entity ;
    dcterms:title     "Book Title"@en ;
    dcterms:creator   "Author Name" ;
    bibo:isbn13       "9780000000000" ;
    bibo:edition      "2nd" ;
    dcterms:date      "2021" ;
    dcterms:publisher "Publisher Name" ;
.

When to use which:

Property Use for Consumed by
dcterms:source All derivation sources (URLs preferred) WIDOCO, LOV, Protégé, documentation generators
prov:wasDerivedFrom Same sources, when traceability matters PROV-aware tools, provenance queries
prov:hadPrimarySource The canonical specification or foundational text Provenance audits, lineage tracking
rdfs:seeAlso Related but non-derivation references (older versions, community pages, alternative formats) General discovery

Anti-patterns:

  • Using dc:source (legacy namespace) — always use dcterms:source instead
  • Using schema:citation for derivation sources — citations are for "how to cite this resource", not "where this resource came from"
  • Omitting dcterms:source and relying only on PROV — most tooling won't find it

Trade-off: Slight redundancy between dcterms:source and prov:wasDerivedFrom pointing to the same URI. This is acceptable — the two serve different consumer ecosystems and the duplication is minimal.

Element-Level Source Attribution

When the source specification has section-level anchors, individual OWL classes carry more specific provenance:

Property Purpose on elements
dcterms:source Specific section URL with fragment identifier — canonical derivation link
prov:wasQuotedFrom Same URL with fragment — indicates skos:definition was quoted verbatim from that section
rdfs:seeAlso Alternative format URLs with fragment for the same section (singlepage, PDF, etc.) 
:MyElement
    a                  owl:Class ;
    skos:prefLabel     "My Element"@en ;
    dcterms:source     <https://spec-publisher.org/spec/chap09.html#sec-My-Element> ;
    prov:wasQuotedFrom <https://spec-publisher.org/spec/chap09.html#sec-My-Element> ;
    rdfs:seeAlso       <https://spec-publisher.org/spec/chap09.html#sec-My-Element>,
                       <https://spec-publisher.org/spec.singlepage/#sec-My-Element> ;
    skos:definition    '''...exact text from the spec definition box...'''@en ;
    skos:scopeNote     '''...explanatory prose following the definition...'''@en ;
.

Rules for element-level attribution:

  • Do NOT repeat the generic ontology-level URL on classes — only use more specific section URLs
  • skos:definition MUST contain the exact formal definition from the spec (the normative definition text)
  • skos:scopeNote contains the explanatory prose that follows the definition
  • Remove figure/example references from scope notes (e.g., "Figure 4-3 shows...")
  • Convert section cross-references to local class links (e.g., "(see :Plateau)" instead of "see Section 12.2.3")
  • Remove spec-internal reference markers (e.g., [G211], [REF-42])
  • arch:domainIncludes / arch:rangeIncludes go on properties only, NEVER on classes

DD-17: Stakeholder as Both Core Concept and Element

Decision: arch:Stakeholder is both a core ontology concept (affecting metamodel design) and a subclass of arch:Element (usable in models).

Rationale: Stakeholders directly affect how the architecture description is organized and thus impact the metamodel itself. At the same time, stakeholders need to appear in architecture models (e.g., ArchiMate motivation views). Making Stakeholder a subclass of Element allows the same instance to serve both roles, benefiting analysis and inference.

DD-18: ReferenceModel as Subclass of Metamodel

Decision: refa:ReferenceModel extends arch:Metamodel.

Rationale: Reference models primarily contain abstract concepts defined as classes — they are type-level artifacts. While they may contain individuals (universals common to a set of concepts, or abstract tropes used as derivation sources), the primary content is definitional.

When reference model concepts are used for derivation, prov:wasDerivedFrom should reference the original concept, maintaining traceability.

DD-19: Force Over Driver for Architecture Decision Influences

Decision: Name the class ad:Force rather than "Driver" or "Motivation" for influences on architecture decisions.

Rationale: "Force" is more generic and encompasses all influences on architecture decisions. "Driver" collides with ArchiMate's Driver concept (which has a more specific meaning). "Motivation" is also a Force but not generic enough. The name aligns with the software architecture literature (Bass, Clements, Kazman) where "architectural forces" is the established term.

DD-20: Presentation Context Scheme for Stakeholder-Specific Views

Decision: Introduce arch:presentationContextScheme to group visual notations and templates by stakeholder audience.

Rationale: The same architecture knowledge needs different visual representations for different audiences (C-Level, Business, DevOps, Architects, Security, Data Management). Rather than creating separate models, presentation contexts act as "themes" that select appropriate visual notations, templates, and abstraction levels from the same underlying knowledge graph.

DD-21: Abstract vs Concrete Elements (ABB/SBB)

Decision: Use arch:isAbstract boolean property to distinguish Architecture Building Blocks (ABBs) from Solution Building Blocks (SBBs).

Rationale: ABBs are abstract, used for modeling patterns, reference architectures, or high-level architectures. SBBs are concrete, used for actual architecture solutions and exist in CMDBs, ITSM solutions, and architecture landscape repositories. This distinction is critical for governance and portfolio management.

DD-22: [Moved] ArchiMate-Specific Decisions

ArchiMate-specific design decisions have been moved to doc/guide/archimate/design-decisions.md. This keeps the repo-wide design decisions document focused on decisions that apply to ALL Linked.Archi ontologies.

Each modeling language module may have its own design-decisions.md for language-specific choices. The repo-wide decisions (DD-1 through DD-21) apply as defaults unless a module-specific decision overrides them.

Conformance Principles

Principles derived from the design decisions above. Use as a quick reference for conformance reviews of new or updated ontology files.

P-1: No arch:Relationship class

The arch:Relationship class has been removed from the core ontology. Relationship types are standard owl:ObjectProperty declarations. No file should declare instances or subclasses of arch:Relationship.

Check: grep -r "arch:Relationship" core/ extensions/ modelingLanguages/ examples/ should return zero hits ( excluding deprecated files and comments).

P-2: No rdf:Statement dependency

arch:QualifiedRelationship does not extend rdf:Statement. No property should be declared as rdfs:subPropertyOf rdf:subject, rdf:object, or rdf:predicate. The bridge to the direct triple is rdf:reifies ( RDF 1.2), not old-style reification.

Check: No rdfs:subClassOf rdf:Statement or rdfs:subPropertyOf rdf:subject/rdf:object/rdf:predicate in any active ontology file.

P-3: Schema-level vs instance-level mapping

arch:unqualifiedForm is a schema-level annotation property used on class and property definitions to declare which unqualified predicate a qualified form corresponds to. It must not appear on instance data. At the instance level, the unqualified predicate is available via rdf:reifies.

P-4: Three-declaration pattern for relationship types

Every relationship type in a metamodel should produce three declarations:

  1. Unqualified predicate — owl:ObjectProperty (e.g., am:serves)
  2. Qualified class — rdfs:subClassOf arch:QualifiedRelationship with arch:unqualifiedForm pointing to the predicate (e.g., am:Serving)
  3. Qualified predicate — owl:ObjectProperty with rdfs:range pointing to the qualified class and arch:unqualifiedForm pointing to the unqualified predicate (e.g., am:qualifiedServes)

See DD-10 for rationale and the Relationship Modeling Guide for full examples.

P-5: No OWL 2 punning for relationship types

Do not use the same IRI as both an owl:ObjectProperty and an owl:Class. The old pattern of declaring a relationship type as a arch:Relationship (making it simultaneously a property and an instance of a class) is retired. Use separate IRIs for the predicate and the qualified class.

P-6: arch:source and arch:target are standalone properties

arch:source and arch:target are standard owl:ObjectProperty declarations on arch:QualifiedRelationship. They have no rdfs:subPropertyOf relationship to rdf:subject or rdf:object.

P-7: Always emit the direct triple

Consumers doing analytics, SPARQL traversal, and reasoning depend on the direct triple. When producing model data, always emit the unqualified triple alongside the qualified resource. The qualified resource alone is not sufficient.