Skip to content

Build Your Own Content Framework and Modeling Tool with Linked.Archi

This guide shows how to extend ArchiMate 4.0 with organization-specific concepts and build a complete content framework — from custom element types through SHACL validation to document generation. The result is a metamodel that a modeling tool can consume to provide a palette, validation, viewpoints, and deliverable generation.

ArchiMate 4.0 serves as the reference implementation. Every pattern shown here is taken from the actual ArchiMate 4.0 semantic assets in this repository.

What a Complete Metamodel Looks Like

A Linked.Archi metamodel is not a single file — it's a collection of resources, each with a specific role:

flowchart LR
    subgraph metamodel["my-metamodel/"]
        direction TB
        onto["my-onto.ttl — Elements + relationships (OWL)"]
        manifest["my-metamodel.ttl — Manifest (entry point for tools)"]
        tax["my-tax.ttl — Classification (SKOS)"]
        shapes["my-shapes.ttl — Validation rules (SHACL)"]
        notation["my-notation.ttl — Visual notation set (shapes, colors, icons)"]
        viewpoints["my-viewpoints.ttl — Viewpoint definitions"]
        templates["my-deliverable-templates.ttl — Document templates with SPARQL"]
        refdata["my-reference-data.ttl — Controlled vocabularies"]
        contexts["my-presentation-contexts.ttl — Stakeholder rendering themes"]
        icons["icons/ — SVG icons (*.svg composites + glyphs/*.svg badges)"]
        tplfiles["templates/*.md.hbs — Handlebars templates for generation"]
    end

ArchiMate 4.0 has all 14 files. You don't need all of them to start — the minimum is the ontology + manifest. Add the others incrementally.

Step 1: Define Your Elements (Ontology)

Every element type subclasses arch:Element. Every relationship follows the three-declaration pattern.

Reference: modelingLanguages/archimate/4.0/archimate4-onto.ttl (1,067 lines, 55 elements, 11 relationships)

@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix arch:    <https://meta.linked.archi/core#> .
@prefix am4:     <https://meta.linked.archi/archimate4/onto#> .
@prefix :        <https://meta.linked.archi/mymodel/onto#> .

# Extend ArchiMate 4.0 with organization-specific concepts
<https://meta.linked.archi/mymodel/onto#>
    a owl:Ontology ;
    owl:imports <https://meta.linked.archi/archimate4/onto#> ;
    dc:title "My Organization Metamodel"@en .

# Custom element extending ArchiMate
:Microservice
    a               owl:Class ;
    rdfs:subClassOf am4:ApplicationComponent ;
    skos:prefLabel  "Microservice"@en ;
    skos:definition "A fine-grained, independently deployable service."@en ;
    arch:prefVisNotation "https://example.com/icons/microservice.svg" .

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

# Custom relationship — three declarations
:dependsOn
    a                    owl:ObjectProperty ;
    skos:prefLabel       "Depends On"@en ;
    arch:domainIncludes  :Microservice ;
    arch:rangeIncludes   am4:ApplicationComponent .

:Dependency
    a                    owl:Class ;
    rdfs:subClassOf      arch:QualifiedRelationship ;
    arch:unqualifiedForm :dependsOn ;
    skos:prefLabel       "Dependency"@en .

:qualifiedDependsOn
    a                    owl:ObjectProperty ;
    rdfs:range           :Dependency ;
    arch:unqualifiedForm :dependsOn .

What a tool gets from this: - Element palette: query ?class rdfs:subClassOf+ arch:Element . FILTER NOT EXISTS { ?class arch:isAbstractClass true } → get only concrete (instantiable) element types with labels and icons - Relationship palette: query ?class rdfs:subClassOf arch:QualifiedRelationship → get all relationship types with arch:unqualifiedForm (the predicate) and arch:domainIncludes/arch:rangeIncludes (valid connections) - Abstract classes (marked with arch:isAbstractClass true) are used for classification and validation but excluded from the palette

Step 2: Create the Metamodel Manifest

The manifest is the entry point for tools. It declares what resources make up the metamodel.

Reference: modelingLanguages/archimate/4.0/archimate4-metamodel.ttl

:MyMetamodel
    a                        arch:Metamodel ;
    skos:prefLabel           "My Organization Metamodel"@en ;
    arch:basedOnFramework    :MyFramework ;
    arch:modelConcepts       <https://meta.linked.archi/mymodel/onto#> ;
    arch:formalRules         <https://meta.linked.archi/mymodel/shapes#> ;
    arch:architectureViewpoints <https://meta.linked.archi/mymodel/viewpoints#> ;
    arch:conceptClassification <https://meta.linked.archi/mymodel/tax#> ;
    arch:notationSet         mynot:MyStandardNotation ;
    arch:hasDeliverableTemplate :MyDocument ;
    arch:referenceData       myref:MyReferenceData ;
    arch:presentationContextScheme mypres:MyPresentationContexts .

What a tool gets from this: A single IRI to discover everything — load the metamodel, follow the properties, and you have the complete modeling language including visual notation.

Step 3: Add Classification (Taxonomy)

SKOS concept schemes organize elements for palette grouping, filtering, and navigation.

Reference: modelingLanguages/archimate/4.0/archimate4-tax.ttl (234 lines)

<https://meta.linked.archi/mymodel/tax#>
    a                skos:ConceptScheme ;
    skos:prefLabel   "My Model Classification"@en ;
    skos:hasTopConcept :BusinessDomain, :TechnologyDomain .

:BusinessDomain
    a skos:Concept ; skos:topConceptOf <https://meta.linked.archi/mymodel/tax#> ;
    skos:prefLabel "Business Domain"@en .

:TechnologyDomain
    a skos:Concept ; skos:topConceptOf <https://meta.linked.archi/mymodel/tax#> ;
    skos:prefLabel "Technology Domain"@en .

# Link OWL classes to SKOS concepts for palette grouping
am4:BusinessActor rdfs:seeAlso :BusinessDomain .
:Microservice rdfs:seeAlso :TechnologyDomain .

What a tool gets from this: Palette groups — "Business Domain" contains BusinessActor, BusinessRole, etc. "Technology Domain" contains Microservice, Node, etc.

Step 4: Add Validation (SHACL Shapes)

SHACL shapes validate model data — required properties, valid relationship source/target types, cardinalities.

Reference: modelingLanguages/archimate/4.0/archimate4-relationship-shapes.ttl (6,573 lines — generated from validity matrix)

# Every Microservice must have a label and resilience level
:MicroserviceShape
    a sh:NodeShape ;
    sh:targetClass :Microservice ;
    sh:property [
        sh:path skos:prefLabel ;
        sh:minCount 1 ;
        sh:message "Every Microservice must have a name."@en ;
    ] ;
    sh:property [
        sh:path :resilienceLevel ;
        sh:minCount 1 ;
        sh:in ( "critical" "high" "medium" "low" ) ;
        sh:message "Microservice must have a resilience level."@en ;
    ] .

# Dependency relationship: source must be Microservice, target must be ApplicationComponent
:DependencyShape
    a sh:NodeShape ;
    sh:targetClass :Dependency ;
    sh:property [
        sh:path arch:source ;
        sh:class :Microservice ;
    ] ;
    sh:property [
        sh:path arch:target ;
        sh:class am4:ApplicationComponent ;
    ] .

What a tool gets from this: Validation on save — red squiggles when a relationship has an invalid source/target, or when a required property is missing.

Step 5: Define Viewpoints

Viewpoints specify which element types are allowed in which view, for which stakeholders, addressing which concerns.

Reference: modelingLanguages/archimate/4.0/archimate4-viewpoints.ttl (440 lines, 23 viewpoints)

:MicroserviceDependencyViewpoint
    a               arch:Viewpoint ;
    skos:prefLabel  "Microservice Dependency View"@en ;
    skos:definition "Shows microservices and their dependencies."@en ;
    arch:includesConcept :Microservice, am4:ApplicationComponent, :Dependency ;
    arch:targetsStakeholder :Developer, :Architect ;
    arch:viewpointFramesConcern archvp:DependencyConcern ;
    arch:viewpointHasPurpose archvp:Designing ;
    arch:viewType arch:Diagram .

What a tool gets from this: Viewpoint-filtered palette — when the user opens a "Microservice Dependency View", only Microservice, ApplicationComponent, and Dependency are available in the palette.

Step 6: Add Deliverable Templates with SPARQL

Deliverable templates define document structure with SPARQL queries that extract data from the knowledge graph.

Reference: modelingLanguages/archimate/4.0/archimate4-deliverable-templates.ttl + templates/*.md.hbs

:MicroserviceCatalog
    a                       arch:DeliverableTemplate ;
    skos:prefLabel          "Microservice Catalog"@en ;
    arch:templateHasSection :MC-S1, :MC-S2 ;
    arch:templateResource   "templates/microservice-catalog.md.hbs"^^xsd:anyURI ;
    arch:templateHasFormat  archdt:MarkdownFormat ;
    arch:templateTargetsPurpose archvp:Informing .

:MC-S1 a arch:TemplateSection ;
    arch:sectionOrder 1 ;
    skos:prefLabel "Microservice Inventory"@en ;
    arch:sectionResultKey "microservices" ;
    arch:sectionQuery """
        PREFIX : <https://meta.linked.archi/mymodel/onto#>
        SELECT ?ms ?label ?resilience WHERE {
            ?ms a :Microservice ;
                skos:prefLabel ?label ;
                :resilienceLevel ?resilience .
        } ORDER BY ?label
    """^^xsd:string .

The Handlebars template renders the query results:

## Microservice Inventory

| Service | Resilience Level |
|---------|-----------------|
{{#each microservices}}
| {{this.label}} | {{this.resilience}} |
{{/each}}

What a tool gets from this: Document generation — execute the SPARQL queries against the model, assemble the JSON context, render the Handlebars template → produce a Markdown/HTML/PDF document.

Step 7: Add Visual Notation (NotationSet)

A notation set defines the default visual appearance for each element and relationship — shape, color, icon, line style. This is what palette generators and diagram editors use to render concepts.

Reference: modelingLanguages/archimate/4.0/archimate4-notation.ttl (generated by .scripts/generate-notation-sets.py)

@prefix arch:     <https://meta.linked.archi/core#> .
@prefix arch-vis: <https://meta.linked.archi/core-vis#> .
@prefix :         <https://meta.linked.archi/mymodel/notation#> .

:MyStandardNotation
    a               arch-vis:NotationSet ;
    skos:prefLabel  "My Model Standard Notation"@en .

:MicroserviceNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor myonto:Microservice ;
    arch-vis:inNotationSet :MyStandardNotation ;
    arch:prefVisNotation  <https://example.com/icons/microservice.svg> ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        arch-vis:shapeType     arch-vis:RoundedRectangle ;
        arch-vis:fillColor     "#C9E7CB" ;
        arch-vis:lineColor     "#000000" ;
        arch-vis:iconSymbol    "https://example.com/icons/glyphs/hexagon-nodes.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:TopRight ;
        arch-vis:defaultWidth  120.0 ;
        arch-vis:defaultHeight 55.0 ;
    ] .

:DependencyNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor myonto:Dependency ;
    arch-vis:inNotationSet :MyStandardNotation ;
    arch-vis:lineStyle    arch-vis:DashedLine ;
    arch-vis:sourceDecor  arch-vis:NoDecoration ;
    arch-vis:targetDecor  arch-vis:OpenArrowhead .

Then link the notation set from the metamodel manifest and presentation contexts:

# In my-metamodel.ttl
:MyMetamodel
    arch:notationSet :MyStandardNotation .

# In my-presentation-contexts.ttl
:ArchitectContext
    arch:usesNotationSet :MyStandardNotation .

What a tool gets from this: - Palette rendering — shape, color, icon, and dimensions for each element type - Relationship rendering — line style and endpoint decorations - Context-aware switching — different audiences can get different notation sets - Rendered images — arch:prefVisNotation SVG for docs and static catalogs

For the full visual notation architecture, see the Visual Notation Guide.

Multiple Notation Sets — Same Model, Different Views

You can define multiple notation sets for the same metamodel. The most common pattern: one set with standard ArchiMate notation (for architects) and another with vendor icons (for developers/ops):

## Standard ArchiMate notation — ShapeWithBadge mode
:MyStandardNotation
    a arch-vis:NotationSet ;
    skos:prefLabel "Standard Notation"@en .

:EC2StandardNotation
    arch-vis:notationFor myonto:EC2Instance ;
    arch-vis:inNotationSet :MyStandardNotation ;
    arch-vis:defaultStyle [
        arch-vis:renderingMode arch-vis:ShapeWithBadge ;
        arch-vis:shapeType     arch-vis:RoundedRectangle ;
        arch-vis:fillColor     "#C9E7F5" ;
        arch-vis:iconSymbol    "https://d1.awsstatic.com/icons/Arch_Amazon-EC2_16.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:TopRight ;
    ] .

## AWS icon notation — IconCentric mode
:AWSIconNotation
    a arch-vis:NotationSet ;
    skos:prefLabel "AWS Architecture Icons"@en .

:EC2IconNotation
    arch-vis:notationFor myonto:EC2Instance ;
    arch-vis:inNotationSet :AWSIconNotation ;
    arch-vis:defaultStyle [
        arch-vis:renderingMode arch-vis:IconCentric ;
        arch-vis:iconSymbol    "https://d1.awsstatic.com/icons/Arch_Amazon-EC2_64.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:Center ;
        arch-vis:defaultWidth  64.0 ;
        arch-vis:defaultHeight 64.0 ;
    ] .

Then link each PresentationContext to the appropriate set:

mypres:ArchitectContext  arch:usesNotationSet :MyStandardNotation .
mypres:DeveloperContext  arch:usesNotationSet :AWSIconNotation .

The underlying model data is identical — only the visual rendering changes based on who's looking. This works for AWS, Azure, GCP, Kubernetes, or any vendor icon set.

Step 8: Add Reference Data and Presentation Contexts

Reference data provides controlled vocabularies (lifecycle states, environment types). Presentation contexts define stakeholder-specific rendering themes.

Reference: modelingLanguages/archimate/4.0/archimate4-reference-data.ttl, archimate4-presentation-contexts.ttl

These are SKOS ConceptSchemes — see the ArchiMate 4.0 files for the pattern.

How a Modeling Tool Consumes This

A tool that understands the Linked.Archi metamodel pattern can:

  1. Discover — load the arch:Metamodel IRI, follow arch:modelConcepts, arch:formalRules, arch:architectureViewpoints, arch:notationSet, etc.
  2. Build palette — query element and relationship classes from the ontology, group by SKOS taxonomy
  3. Render palette — read arch:notationSet → query VisualNotation instances → get shape, color, icon per concept
  4. Filter by viewpoint — query arch:includesConcept to restrict the palette per view
  5. Validate — load SHACL shapes, validate on every edit
  6. Render elements — use arch-vis:defaultStyle for shape/color/icon, or arch:prefVisNotation for pre-rendered SVG
  7. Generate documents — execute arch:sectionQuery SPARQL, render Handlebars templates
  8. Adapt to stakeholder — switch PresentationContext → follow arch:usesNotationSet → get context-appropriate notation
# Tool bootstrap query — discover everything from the metamodel IRI
PREFIX arch: <https://meta.linked.archi/core#>

SELECT ?property ?value WHERE {
    <https://meta.linked.archi/mymodel/metamodel#MyMetamodel> ?property ?value .
    VALUES ?property {
        arch:modelConcepts
        arch:formalRules
        arch:architectureViewpoints
        arch:conceptClassification
        arch:hasDeliverableTemplate
        arch:referenceData
        arch:presentationContextScheme
    }
}

The ArchiMate 4.0 Reference

ArchiMate 4.0 is the most complete reference implementation in this repository:

Resource File Lines What it demonstrates
Ontology archimate4-onto.ttl 1,067 55 elements, 11 relationships, three-declaration pattern
Metamodel archimate4-metamodel.ttl 130 Manifest linking all resources
Taxonomy archimate4-tax.ttl 234 Domain-based classification
Notation archimate4-notation.ttl ~700 Visual notation set — shape, color, icon per concept
Relationship shapes archimate4-relationship-shapes.ttl 13,237 Generated: 285 qualified + 42 unqualified shapes
Element shapes archimate4-element-shapes.ttl 504 23 metamodel pattern constraints
Derivation rules archimate4-derivation-rules.ttl 831 DR1-DR8 (valid) + PDR1-PDR12 (potential)
Principle shapes archimate4-principle-shapes.ttl 787 20 governance principle shapes
Viewpoint shapes archimate4-viewpoint-shapes.ttl 86 Viewpoint conformance
Viewpoints archimate4-viewpoints.ttl 440 23 viewpoints with stakeholders
Deliverable templates archimate4-deliverable-templates.ttl 223 3 documents with SPARQL
Reference data archimate4-reference-data.ttl 39 Lifecycle, environment, criticality
Reference models archimate4-reference-models.ttl 38 Patterns and industry models
Presentation contexts archimate4-presentation-contexts.ttl 41 5 stakeholder themes with notation set links
Templates templates/*.md.hbs 3 files Handlebars document templates

Study these files to understand the patterns, then apply them to your own metamodel.

ArchiMate 4.0 — Complete Reference Implementation

The ArchiMate 4.0 asset set is now a complete reference implementation with all semantic asset types:

For a complete worked example that applies these patterns to a real scenario, see the Cloud Platform Walkthrough — it extends ArchiMate 4.0 with microservices, containers, and event-driven concepts, with full design rationale for each choice.

References