Modeling Languages Guide¶
This guide explains the modeling language ontologies in modelingLanguages/ — what each provides, how they relate through the arch:core foundation, how to choose and combine them, and how to author models using them.
For comparative analysis of the modeling notations themselves (ArchiMate vs C4 vs UML), see the articles in doc/articles/.
1. Overview¶
Each modeling 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 modeling 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 — 7 elements, 7 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 & bmcAll 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.
Use when: You need enterprise-wide modeling 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 catalog model.
| Aspect | Content |
|---|---|
| Elements | 7 types: Component, System, API, Resource, Domain, User, Group |
| Relationships | 7 types: Ownership, SystemMembership, APIProvision, APIConsumption, ResourceUsage, DomainMembership, GroupMembership |
| Viewpoints | 5 viewpoints: ServiceCatalog, SystemDependency, APIDependency, OwnershipMatrix, DomainOverview |
| SHACL shapes | Per-relationship-type domain/range constraints |
| Taxonomy | Software entities vs organizational entities |
| Reference data | Component lifecycle (experimental/production/deprecated), component types (service/website/library), API types (OpenAPI/AsyncAPI/GraphQL/gRPC) |
Use when: You need to integrate a Backstage developer portal catalog into the knowledge graph, adding ownership, API tracking, lifecycle, and domain organization.
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 | Per-ontology constraint sets |
| Viewpoints | 4 viewpoints: Process, Collaboration, Choreography, Conversation |
| Alignment | Suite-level alignment ontology connecting BPMN to Linked.Archi core |
| Reference | OMG BPMN 2.0.2 formal/2013-12-09 |
Use when: You need detailed behavioral process modeling — 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).
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 |
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 | v3 and v4 element/relationship ontologies |
| Taxonomy | LeanIX fact sheet types |
| Viewpoints | Application landscape, IT component, business capability viewpoints |
Use when: You need to integrate LeanIX data into the knowledge graph for portfolio management, TIME assessments, or technology lifecycle analysis.
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. Colors: green
#75F0A5(Identity), blue#9DB9F6(Architecture), pink#F985B4(Experience), with intersection colors cyan/orange/purple. - Alternative (v1) — all elements rendered as circles with facet-colored fills and centered glyphs inside. More compact and iconic, suitable for high-density maps.
Both sets follow the same color 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 Modeling 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:Elementsubclasses → 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 labeling - All models reference
arch:Metamodel→ discoverable viaarch:modelConformsToMetamodel - All viewpoints are
arch:Viewpointinstances → consistent viewpoint framework - Core SHACL shapes apply to all →
skos:prefLabelrequired,arch:source/arch:targetrequired on relationships
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 |
Backstage is authoritative for ownership |
| Lifecycle | Backstage bs:lifecycle |
Backstage is authoritative for runtime lifecycle |
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 catalog with ownership | Backstage |
| Detailed process/workflow modeling | 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¶
A metamodel can import multiple languages. For example, an organization using ArchiMate for enterprise modeling, C4 for developer documentation, and Backstage for the service catalog:
@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:ownedBy ex:OrdersTeam ;
bs:lifecycle "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¶
5.1 As Turtle files (recommended for semantic precision)¶
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) | converters/archimate/ |
RDF typed with am: classes |
| Camunda, Signavio (BPMN) | converters/bpmn/ |
RDF typed with bpmn: classes |
| PlantUML (class, component, sequence, use case) | converters/plantuml/ |
RDF typed with appropriate classes |
All converters produce three named graphs (semantic, views, provenance) and support YAML type-mapping overrides for custom ontology alignment.
5.3 From Structurizr DSL (with ArchiMate tags)¶
Use Structurizr archetypes and tags to carry ArchiMate type information, then convert the workspace JSON to RDF. See ArchiMate in Structurizr DSL for the approach, limitations, and alternatives.
5.4 Extending with custom concepts¶
Any language can be extended with organization-specific concepts:
@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 .
See the Fortis banking example for a real-world extension.
6. Validation¶
Every language has SHACL shapes that validate model data. Run validation via:
# 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 Modeling 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 modeling patterns | ArchiMate 4.0 Modeling Guide |
| ArchiMate design decisions | ArchiMate Design Decisions |
| EDGY modeling patterns | EDGY Modeling 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 modeling notations themselves. They are maintained in doc/practice/: