Skip to content

Modelling Languages Guide — Choose, Combine, and Author

Every architecture team faces the same question: "which notation do we use?" — and the real answer is usually "several, depending on the audience." Developers use C4, enterprise architects use ArchiMate, process analysts use BPMN, platform teams use Backstage. The problem isn't choosing one — it's making them work together.

This guide explains how the modelling language ontologies in modelingLanguages/ solve that problem — what each provides, how they compose through the shared arch:core foundation, how to choose and combine them, and how to author models using them.

1. Overview

Each modelling language in this repository is formalized as an RDF/OWL ontology that imports arch:core. This means every language shares the same foundational concepts (arch:Element, arch:QualifiedRelationship, arch:View, arch:Viewpoint, arch:Metamodel) and the same relationship modelling pattern (three-declaration qualified relationships, SHACL validation, SKOS classification).

flowchart TD
    core["arch:core"]
    am["modelingLanguages/archimate/<br/>ArchiMate 3.2 + 4.0 — 62 elements, 11 relationships"]
    c4["modelingLanguages/c4/<br/>C4/Structurizr — 6 elements, 3 relationships"]
    bs["modelingLanguages/backstage/<br/>Backstage Catalog — 8 elements, 13 relationships"]
    bpmn["modelingLanguages/bpmn/<br/>BPMN 2.0.2 — full CMOF mapping (144 classes)"]
    bpmnlite["modelingLanguages/bpmn-lite/<br/>BPMN Lite — EA-level thin lift (29 classes)"]
    lx["modelingLanguages/leanIX/<br/>SAP LeanIX v3/v4"]
    bmc["modelingLanguages/bmc/<br/>Business Model Canvas"]

    core --> am & c4 & bs & bpmn & bpmnlite & lx & bmc

All languages can coexist in the same knowledge graph. An am:ApplicationComponent and a c4:SoftwareSystem and a bs:System can all describe the same real-world system, linked by shared IRIs or owl:sameAs.

2. Language Summaries

2.1 ArchiMate 3.2 (modelingLanguages/archimate/)

The most comprehensive metamodel. Covers the full enterprise architecture scope.

Aspect Content
Elements 62 types across 7 layers (Motivation, Strategy, Business, Application, Technology, Physical, I&M)
Relationships 11 types (Composition, Aggregation, Assignment, Realization, Serving, Access, Influence, Triggering, Flow, Specialization, Association)
Viewpoints 23 example viewpoints with stakeholders, concerns, aspects, perspectives
SHACL shapes Relationship validity (generated from matrix), element constraints (24 shapes), governance principles (20 shapes), viewpoint conformance
Derivation rules DR1-DR8 (valid) + PDR1-PDR12 (potential) from ArchiMate Appendix B
Taxonomy SKOS classification by layer and by aspect
Reference data Lifecycle states, environment types, criticality levels
Reference models Architecture patterns (Layered, Microservices, Event-Driven, SOA), industry models (BIAN, TM Forum, ACORD)
Deliverable templates Architecture Definition Document, Requirements Spec, Principles Document
Presentation contexts Executive, Architect, Developer, Operations, Governance themes

Files: See modelingLanguages/archimate/README.md for the complete file listing and versioning strategy.

Versions: 3.2 and 4.0 live side by side in 3.2/ and 4.0/, each with its own arch:Metamodel individual — ammm:ArchiMate3.2 and am4mm:ArchiMate4 — because a model conforms to a release, not to the language in general. Both point arch:basedOnFramework at one version-neutral IRI, amfw:ArchiMateFramework, declared in modelingLanguages/archimate/archimate-framework.ttl above the version directories. Select every ArchiMate model whatever its release with arch:modelConformsToMetamodel/arch:basedOnFramework amfw:ArchiMateFramework; select one release with arch:modelConformsToMetamodel. The old per-version framework IRIs under archimate3/metamodel# and archimate4/metamodel# are deprecated — see DD-25.

Use when: You need enterprise-wide modelling with cross-layer traceability (strategy → business → application → technology), formal governance, impact analysis, or compliance validation.

2.2 C4/Structurizr (modelingLanguages/c4/)

Lightweight metamodel for software architecture visualization.

Aspect Content
Elements 6 types: Person, SoftwareSystem, Container, Component, DeploymentNode, InfrastructureNode
Relationships 3 types: Using, Containment (hasContainer, hasComponent), Deployment (deployedOn)
Viewpoints 10 viewpoints (SystemContext, ContainerView, ComponentView, DeploymentView, SystemLandscape, DynamicView, plus filtered variants)
SHACL shapes Per-relationship-type domain/range constraints
Taxonomy SKOS classification by C4 level
Deliverable templates System Architecture Document, Deployment Guide
Reference data Container types (service, database, queue, webapp), deployment environments
Presentation contexts Developer, Architect, Stakeholder themes

Use when: You need developer-friendly software architecture documentation with progressive zoom (Context → Container → Component → Code) and deployment views.

2.3 Backstage (modelingLanguages/backstage/)

Maps the Backstage developer portal catalogue model, derived from the Software Catalog documentation and from the JSON Schemas in packages/catalog-model and plugins/scaffolder-common in github.com/backstage/backstage. Where the rendered docs and the schemas disagree, the schemas win and the term records the divergence.

Aspect Content
Elements 8 types: Component, System, API, Resource, Domain, User, Group, Template
Relationships 13 types: Ownership, SystemMembership, APIProvision, APIConsumption, Dependency, ResourceUsage, DomainMembership, GroupMembership, GroupParentage, ComponentComposition, DomainHierarchy, TechDocsDelegation, Scaffolding
Value vocabularies 9, as named individuals (DD-23): LifecycleState, ApiVisibility, StatusLevel, ComponentType, APIType, ResourceType, GroupType, SystemType, DomainType
Viewpoints 7 viewpoints: ServiceCatalog, SystemDependency, APIDependency, OwnershipMatrix, DomainOverview, OrganizationStructure, LifecyclePortfolio
SHACL shapes Per-relationship-type domain/range constraints, entity identity (bs:name), naming (skos:prefLabel), status items, kind-specific property placement, vocabulary closure
Taxonomy Software entities vs organizational entities
Reference data Cross-module correspondences only (e.g. lifecycle ↔ Architecture Processes stages via skos:closeMatch) — the value vocabularies themselves live in the ontology as of 0.3.0
Scope 8 of the descriptor format's 9 kinds. The Location kind is deliberately not modelled, along with a Template's spec.parameters/spec.steps and a status item's error object — see the SCOPE STATEMENT on the ontology header, which gives the reasoning and an alternative for each

Use when: You need to integrate a Backstage developer portal catalogue into the knowledge graph, adding ownership, API tracking, lifecycle, scaffolding provenance, and domain organization.

Before filling an apparent gap: the bs: namespace is published, so a converter must not mint terms in it — a term invented there looks to a consumer like part of the Backstage vocabulary while nothing defines it. Read the scope statement first; if the omission is not listed there, it is worth reporting rather than patching. Anything genuinely local goes in a namespace you own, as a subproperty of bs:label or bs:externalIdentifier where one of those families fits.

2.4 BPMN 2.0.2 (modelingLanguages/bpmn/)

Full OWL mapping of the BPMN 2.0.2 specification from the OMG XMI/CMOF source, validated against the normative XSD and CMOF artifacts.

Aspect Content
Ontologies Core BPMN (130+ classes), Infrastructure, BPMNDI (diagram interchange), DC (diagram common), DI (diagram interchange base)
SHACL shapes One document per ontology module — 156 node shapes in total
Viewpoints 4 viewpoints: Process, Collaboration, Choreography, Conversation
Alignment Declared inline in linkedarchi-bpmn-onto.ttl — 11 roots reach 49 arch:Element classes; 12 connector classes are arch:QualifiedRelationship
Reference OMG BPMN 2.0.2 formal/2013-12-09

Use when: You need detailed behavioural process modelling — lanes, gateways, events, sub-processes, message flows. Complements ArchiMate (which models processes at a higher abstraction) and C4 (which doesn't model processes at all).

Each ontology module has its own shape document, so callers can validate a subset:

Shapes Constrains Node shapes
bpmn/onto-shapes Semantic model — activities, events, gateways, flows, data 135
bpmn/infra-shapes bpmn:definitions container and imports 2
bpmn/di-shapes BPMNDI — BPMNDiagram, BPMNPlane, BPMNShape, BPMNEdge, BPMNLabel 6
bpmn/di-core-shapes Abstract DI classes — Diagram, Shape, Edge, Label, Style 10
bpmn/dc-shapes DC value types — Bounds, Point, Font 3

The first two apply to normalized converter output and are the default set. The last three constrain raw diagram-interchange geometry, so they only have targets when geometry is emitted verbatim rather than flattened into archvis:bounds-*.

Load these documents directly. bpmn/suite#shapes is an owl:imports aggregate, and SHACL processors do not dereference imports, so loading it alone validates nothing.

Cardinality note: the shapes were derived from the BPMN CMOF metamodel, which marks attributes carrying a spec default (isForCompensation, startQuantity, ...) and bpmn:name as lowerBound=1 even though they are optional in serialized BPMN XML. Those sh:minCount assertions were removed. sh:maxCount, sh:datatype, sh:class and sh:in are retained, and genuinely required attributes (targetNamespace, bpmn:import attributes, participantRefs [2..*]) keep their minimums.

2.4b BPMN Lite (modelingLanguages/bpmn-lite/)

Simplified BPMN profile for EA-level reasoning — a "thin lift" covering only constructs with cross-model semantic value.

Aspect Content
Ontologies 29 classes: Process, Task (7 types), Event (4 types), Gateway (4 types), Participant, Lane, DataObject, DataStore, Message
SHACL shapes Constraint set with eventType validation
Relationships SequenceFlow, MessageFlow, DataAssociation
Alignment Direct rdfs:subClassOf arch:Element; skos:exactMatch links to full BPMN classes

Framework identity: BPMN Lite is a profile of BPMN, not a separate notation, so it shares BPMN's framework IRI — bpmnlmm:BPMNLite points arch:basedOnFramework at bpmnmm:BPMNFramework. One hop from that IRI returns both readings; choose between them with arch:modelConformsToMetamodel, which is the question that actually differs. The locally minted bpmn-lite/metamodel#BPMNFramework is deprecated (DD-25).

Use when: You need cross-model EA queries (BPMN + ArchiMate + C4), governance validation ("which processes handle PII?"), or a lightweight process layer in the knowledge graph. Layout stays in the original .bpmn file.

See also: BPMN Deep Dive for a detailed comparison of both profiles with examples.

2.5 LeanIX (modelingLanguages/leanIX/)

Maps the SAP LeanIX Meta Model (v3 and v4).

Aspect Content
Ontologies v4 fact sheet types, 16 relationships and the fact sheet attributes; v3 fact sheet types, elements only
Metamodels One manifest per meta model version, both on one framework individual
Taxonomy LeanIX fact sheet types
Viewpoints Application landscape, IT component, business capability viewpoints
Shapes Fact sheet naming for both namespaces, v4 attribute value sets, and one endpoint shape per relationship type
Example examples/leanix-docs-example/ — a landscape built from the examples in SAP's own documentation, validated by --shacl leanix

Use when: You need to integrate LeanIX data into the knowledge graph for portfolio management, TIME assessments, or technology lifecycle analysis.

Watch for: fact sheet lifecycle does not use a LeanIX term. Emit ap:atLifecycleStage with the stages from the Architecture Processes extension, whose canonical five-stage set was derived from LeanIX's own lifecycle documentation and maps back to it with skos:closeMatch; lmm:LifecyclePhase adds only the date a stage began, which ap: has no construct for. Status and subscription type are named individuals rather than strings, so lmm:factSheetStatus "ACTIVE" is a validation error — the value is lmm:StatusActive, the individual whose skos:notation is that token. Workspace-defined fields have no term and should not: they are per-tenant, so they belong in a namespace the operator owns.

2.6 Business Model Canvas (modelingLanguages/bmc/)

Maps the Business Model Canvas (Osterwalder) as a SKOS-based metamodel.

Use when: You need to connect business model elements (value propositions, customer segments, channels, revenue streams) to the architecture knowledge graph.

2.7 EDGY 23 (modelingLanguages/edgy/)

An open-source Enterprise Design language by Intersection Group. Provides four base elements (People, Outcome, Activity, Object), twelve facet/intersection elements across three facets (Identity, Architecture, Experience), three relationship types (Link, Flow, Tree), and two label types (Tagging, Metrics). 24 pre-defined core links connect elements across facets.

Asset Content
edgy-onto.ttl 21 classes, 24 core link properties, 5 base element properties, 2 label properties
edgy-tax.ttl SKOS taxonomy — base, facet (by category), intersection, relationships, labels
edgy-metamodel.ttl Metamodel manifest (entry point)
edgy-shapes.ttl SHACL shapes — element, relationship, and core link validation
edgy-viewpoints.ttl 9 viewpoints with stakeholders and concerns
edgy-notation.ttl Visual notation set (default, v2) — proper EDGY shapes
edgy-reference-data.ttl Asset types, metric categories, maturity levels, channel types
edgy-deliverable-templates.ttl 7 document templates (enterprise overview, capability map, journey, etc.)
icons/ SVG icons for all elements, relationships, and labels
notation-v1/ Alternative notation set (v1) — circle-based iconic style

Visual notation: Two notation sets are available, selectable via arch-vis:NotationSet:

  • Default (v2) — uses the canonical EDGY shapes: RoundedRectangle for Outcome-family, RightArrow (pentagon) for Activity-family, Rectangle for Object-family, and a person silhouette for People. Colours: green #75F0A5 (Identity), blue #9DB9F6 (Architecture), pink #F985B4 (Experience), with intersection colours cyan/orange/purple.
  • Alternative (v1) — all elements rendered as circles with facet-coloured fills and centred glyphs inside. More compact and iconic, suitable for high-density maps.

Both sets follow the same colour mapping and element semantics; they differ only in shape rendering.

Use when: You need a simple, accessible language for cross-disciplinary enterprise design — bridging business strategy, architecture, and customer experience teams. Complements ArchiMate with identity and experience perspectives.

References: - EDGY Modelling Guide — how to author EDGY models as Turtle with Linked.Archi, including a worked example (Meridian Insurance Group) - EDGY Official Wiki — element definitions, example maps, and visual language - Enterprise Design Cookbook with EDGY — comprehensive practical guide by Eero Hosiaisluoma covering facets, elements, methods, patterns, service blueprints, capability maps, and worked examples (PDF) - Intersection Group — the creators of EDGY, community, learning resources, and publications - EDGY 23 Language Foundations — the official EDGY book by Milan Guenther & Wolfgang Goebl

3. How the Languages Relate

3.1 Shared foundation

Every language imports arch:core. This means:

  • All elements are arch:Element subclasses → queryable with ?x a arch:Element
  • All relationships follow the three-declaration pattern → arch:source, arch:target, arch:unqualifiedForm
  • All elements carry skos:prefLabel → consistent labelling
  • All models reference arch:Metamodel → discoverable via arch:modelConformsToMetamodel
  • Every metamodel is a version of one arch:Framework → select a language regardless of release with arch:modelConformsToMetamodel/arch:basedOnFramework, and a specific release with arch:modelConformsToMetamodel (DD-25)
  • All viewpoints are arch:Viewpoint instances → consistent viewpoint framework
  • Core SHACL shapes apply to all → arch:source/arch:target required on every relationship

Labelling is the exception to "core shapes apply to all". core-shapes.ttl carries no label rule, because arch:Element includes nodes that notations legitimately leave unnamed — BPMN gateways and events, ArchiMate junctions, UML transitions. Each language states its own naming rule in its own shapes, so validating labels means loading that language's shapes document (DD-24). Where a specification requires no name anywhere — UML is the case — the rule lives in a separate opt-in *-publication-shapes document rather than in the conformance shapes (UML-DD-14).

3.2 Cross-language integration points

Integration Point Languages How
System identity ArchiMate am:ApplicationComponent ↔ C4 c4:SoftwareSystem ↔ Backstage bs:System Same IRI or owl:sameAs / skos:exactMatch
Deployable unit ArchiMate am:ApplicationComponent (nested) ↔ C4 c4:Container ↔ Backstage bs:Component Same IRI or naming convention
API contract ArchiMate am:ApplicationInterface + am:ApplicationService ↔ Backstage bs:API Same IRI or skos:exactMatch
Infrastructure ArchiMate am:Node / am:Device / am:SystemSoftware ↔ C4 c4:DeploymentNode ↔ Backstage bs:Resource Same IRI or naming convention
Business process ArchiMate am:BusinessProcess ↔ BPMN bpmn:Process arch:refines or owl:sameAs
Ownership Backstage bs:ownedBy → bs:Group or bs:User Backstage is authoritative for ownership
Lifecycle Backstage bs:lifecycleState → bs:LifecycleState individual Backstage is authoritative for runtime lifecycle; bs:lifecycle (plain string) is deprecated as of 0.3.0

3.3 Choosing languages for your metamodel

If your concern is... Use
Full enterprise architecture (strategy → technology) ArchiMate
Developer-facing system documentation C4
Runtime service catalogue with ownership Backstage
Detailed process/workflow modelling BPMN
Application portfolio management LeanIX or ArchiMate + TIME framework
Business model alignment BMC + ArchiMate Strategy layer
All of the above Compose them — they all share arch:core

4. Composing Multiple Languages in One Metamodel

A metamodel can import multiple languages. For example, an organization using ArchiMate for enterprise modelling, C4 for developer documentation, and Backstage for the service catalogue.

Paste this into a metamodel manifest to declare a multi-language composition:

@prefix arch: <https://meta.linked.archi/core#> .
@prefix :     <https://model.example.com/metamodel#> .

:OurMetamodel a arch:Metamodel ;
    skos:prefLabel "Our Enterprise Metamodel"@en ;
    arch:modelConcepts
        <https://meta.linked.archi/archimate3/onto#>,
        <https://meta.linked.archi/c4/onto#>,
        <https://meta.linked.archi/backstage/onto#> ;
    arch:formalRules
        <https://meta.linked.archi/core-shapes#>,
        <https://meta.linked.archi/archimate3/shapes#>,
        <https://meta.linked.archi/c4/shapes#>,
        <https://meta.linked.archi/backstage/shapes#> .

Models conforming to this metamodel can use elements from all three languages in the same graph:

# ArchiMate: business context
ex:OrderFulfillment a am:Capability .
ex:OrderPlacement a am:BusinessService ;
    am:realizes ex:OrderFulfillment .

# C4: developer view
ex:OrderMgmt a c4:SoftwareSystem .
ex:OrdersAPI a c4:Container ;
    c4:technology "Spring Boot" .
ex:OrderMgmt c4:hasContainer ex:OrdersAPI .

# Backstage: operational catalog
ex:OrdersAPI a bs:Component ;
    bs:name "orders-api" ;
    bs:ownedBy ex:OrdersTeam ;
    bs:lifecycleState bs:Production ;
    bs:providesAPI ex:OrdersOpenAPI .

# Cross-language link
ex:OrdersAPI am:assignedTo ex:OrderPlacementService .
ex:OrderPlacementService a am:ApplicationService ;
    am:realizes ex:OrderPlacement .

SPARQL queries traverse across all three seamlessly.

5. Authoring Models

Write .ttl files directly. See Semantic Architecture as Code for the full workflow with Makefile, CI/CD, and SPARQL views.

5.2 From existing tools via converters

Source Tool Converter Output
Archi, Sparx EA, BiZZdesign (ArchiMate) archimate2linkedarchi RDF typed with am: classes
Camunda, Signavio (BPMN) bpmn2linkedarchi RDF typed with bpmn: classes
PlantUML (class, component, sequence, use case, state) plantuml2linkedarchi RDF typed with uml: classes
Structurizr workspace JSON (C4) structurizr2linkedarchi RDF typed with c4: and Structurizr extension classes
Backstage catalogue YAML backstage2linkedarchi RDF typed with bs: classes
SAP LeanIX fact sheet export, optionally with a diagram export leanix2linkedarchi RDF typed with lmm: classes

The converters share a graph contract, not an identical graph inventory. Each model has semantic and curated model content plus provenance when enabled; view content is emitted only when the source supplies it. Backstage has no views, LeanIX requires --diagrams-export for views, and Structurizr and LeanIX supply no authored geometry. Backstage is currently the only converter that partitions semantic facts by input file. YAML type-mapping uses a shared superset schema with some converter-specific sections. See DD-15 and Converters.

5.3 From Structurizr DSL

Export the DSL to Structurizr workspace JSON, then use structurizr2linkedarchi to preserve its C4 and Structurizr semantics in RDF. The current converter does not interpret ArchiMate tags as ArchiMate classes; that tag-driven projection remains a possible custom extension. See ArchiMate in Structurizr DSL for the distinction, limitations, and alternatives.

5.4 Extending with Custom Concepts (Organization-Specific Elements)

Any language can be extended with organization-specific concepts. Paste this into a custom ontology file to create a Microservice element type that inherits all ArchiMate ApplicationComponent semantics:

@prefix am:   <https://meta.linked.archi/archimate3/onto#> .
@prefix arch: <https://meta.linked.archi/core#> .
@prefix :     <https://model.example.com/custom#> .

# Custom element extending ArchiMate
:Microservice
    a               owl:Class ;
    rdfs:subClassOf am:ApplicationComponent ;
    skos:prefLabel  "Microservice"@en ;
    skos:definition "A fine-grained, independently deployable service."@en .

# Custom property
:resilienceLevel
    a                   owl:DatatypeProperty ;
    skos:prefLabel      "Resilience Level"@en ;
    arch:domainIncludes :Microservice ;
    rdfs:range          xsd:string .

6. Validation — Run SHACL Shapes Against Your Models

Every language has SHACL shapes that validate model data. Run these commands to check your models:

# Validate against a specific language
.scripts/validate.sh --shacl archimate
.scripts/validate.sh --shacl c4
.scripts/validate.sh --shacl backstage

# Validate custom model against multiple shape sets
.scripts/validate.sh --shacl mymodel.ttl \
    core/core-shapes.ttl \
    modelingLanguages/archimate/3.2/archimate3.2-relationship-shapes.ttl \
    modelingLanguages/backstage/backstage-shapes.ttl

# Full CI run
.scripts/validate.sh --ci

See Validation Guide for details on the two-layer shapes architecture and how to add custom profiles.

7. Further Reading

Topic Document
Core ontology classes and properties Ontology Reference
Qualified relationship pattern Relationship Modelling Guide
Design rationale Design Decisions
Creating a new metamodel Quick Start Guide
Validation pipeline Validation Guide
Real-world scenarios Use Cases
ArchiMate ontology details ArchiMate Ontology Suite
ArchiMate 4.0 modelling patterns ArchiMate 4.0 Modelling Guide
ArchiMate design decisions ArchiMate Design Decisions
EDGY modelling patterns EDGY Modelling Guide
Architecture-as-code workflow Semantic Architecture as Code
DSL options for authoring ArchiMate in Structurizr DSL and Beyond

Practice Guides

The following provide in-depth comparisons of the modelling notations themselves. They are maintained in doc/practice/: