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 — 11 elements, 4 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"]
    basic["modelingLanguages/basic/<br/>Basic — minimal example language"]

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

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 The 25 example viewpoints of Appendix C, with their stakeholders, concerns and purposes
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 11 types: Person, SoftwareSystem, Container, Component; the container kinds Database, MobileApp and ClientSideWebApp and the external ExternalPerson and ExternalSoftwareSystem, as subclasses; DeploymentNode and InfrastructureNode (Structurizr)
Relationships 4 types: Using, Container Containment, Component Containment (c4:), Deployment (structurizr: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 technologies (web app, mobile app, desktop app, API service, microservice, database, message broker, file system, serverless function), deployment environments
Presentation contexts Developer, Architect, Stakeholder themes
Visual notation Structurizr's rendering of the C4 model: shape-only boxes, a person shape, a database as a cylinder, a mobile app in a device frame, a client-side web application in a browser window, external people and systems in grey — each a class with a descriptor of its own
Sources Every class and property links (rdfs:seeAlso) to its c4model.com page and its Structurizr DSL section

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-presentation-contexts.ttl Two audiences — Enterprise designer (v2 notation) and Overview map reader (v1 notation)
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. The manifest names the default (v2) with its single arch:notationSet; v1 is selected by presentation context — the Overview map reader context in https://meta.linked.archi/edgy/presentation-contexts# names it with arch:usesNotationSet:

  • Default (v2) — uses the canonical EDGY shapes: RoundedRectangle for Outcome-family, a right arrow (edgynot:RightArrow) for Activity-family, Rectangle for Object-family, a person silhouette for People, and pills (edgynot:Pill) with the text inside for tags and metrics; names are black (arch-vis:fontColor) on the white-bordered facet colours. 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 cover the same 16 elements and three relationships, and both colour elements by facet and intersection. They differ in shape and in colour: v1 uses yellow for Identity, blue for Architecture and red for Experience, with green, orange and purple intersections, while v2 uses green, blue and pink, with cyan, orange and purple intersections. v1 has no descriptors for the two labels, Tagging and Metrics, so tools draw them in the default set's look.

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

2.8 Basic (modelingLanguages/basic/)

A minimal Linked.Archi modelling language, in draft, published at https://meta.linked.archi/basic with the namespace https://meta.linked.archi/basic#. It defines three element types (Node, SpecialNode, GroupNode) and three qualified relationship types (Association, Aggregation, Connection) directly on the core ontology. It is small enough for examples of restrictions and inference, and it is the generic language: Connection relates any two elements, of any language, so Basic added beside another language lets a modeller relate what that language has no relationship for, and its notation sets give renderers a generic way to draw elements and relationships that have no language-specific notation.

Asset Content
basic-onto.ttl 3 element classes and 3 qualified relationship types, each with its three declarations
basic-metamodel.ttl Metamodel manifest (entry point), https://meta.linked.archi/basic/metamodel#Basic
basic-tax.ttl SKOS taxonomy — one axis grouping elements and relationships
basic-presentation-contexts.ttl Two audiences — Modeller (rectangle set) and Workshop participant (bubble set)
basic-notation.ttl + icons/ Visual notation set (default) — rectangles
notation-bubble/ Alternative visual notation set — circles (bubbles)

Visual notation: The manifest names the rectangle set, https://meta.linked.archi/basic/notation#BasicRectangleNotation, with its single arch:notationSet, which makes it the default. The bubble set, https://meta.linked.archi/basic/notation-bubble#BasicBubbleNotation, is selected by the Workshop participant context in https://meta.linked.archi/basic/presentation-contexts#. Both sets describe arch:Element and arch:QualifiedRelationship generically, plus Association and Aggregation; Connection uses the generic relationship descriptor. Elements are very light grey-green rectangles or circles. Relationships carry no colour and are drawn black: Association is a plain line, Aggregation has a hollow diamond at the whole (source) end, and a relationship class that nothing nearer describes gets an open arrowhead at the target. The Visual Notation Guide gives the fallback order.

Use when: You need a small, neutral language for examples, tests or teaching, or a generic notation for elements and relationships that no language-specific set covers.

Paste this into a model file to aggregate a node into a group node — the direct triple plus the qualified relationship it stands for:

@prefix arch:  <https://meta.linked.archi/core#> .
@prefix basic: <https://meta.linked.archi/basic#> .
@prefix skos:  <http://www.w3.org/2004/02/skos/core#> .
@prefix ex:    <https://model.example.com/basic-demo/> .

ex:PlatformTeam   a basic:GroupNode ; skos:prefLabel "Platform team"@en .
ex:BillingService a basic:Node      ; skos:prefLabel "Billing service"@en .

# Direct triple
ex:PlatformTeam basic:aggregation ex:BillingService .

# Qualified relationship
ex:PlatformTeam basic:qualifiedAggregation ex:TeamAggregatesBilling .
ex:TeamAggregatesBilling
    a           basic:Aggregation ;
    arch:source ex:PlatformTeam ;
    arch:target ex:BillingService .

List Basic's element and relationship types by taxonomy group (load basic-onto.ttl and basic-tax.ttl):

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?groupLabel ?class ?label WHERE {
    ?class skos:inScheme <https://meta.linked.archi/basic/tax#> ;
           skos:broader  ?group ;
           skos:prefLabel ?label .
    ?group skos:prefLabel ?groupLabel .
    FILTER NOT EXISTS { ?class skos:narrower ?child }
    FILTER(lang(?label) = "en")
}
ORDER BY ?groupLabel ?label

References: - Basic ontology — elements and relationships - Basic metamodel — the manifest and everything it ties together

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 structurizr: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. To check a model, load it as the data graph, and the core shapes with each of its languages' shapes as the shapes graph — the shapes of several languages combine:

data:   mymodel.ttl
shapes: core/core-shapes.ttl
        modelingLanguages/archimate/3.2/archimate3.2-relationship-shapes.ttl
        modelingLanguages/backstage/backstage-shapes.ttl

The repository validates each language's shapes on every push, over its ontology or a reference example.

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/: