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:

my-metamodel/
  ├── my-onto.ttl                    ← Elements + relationships (OWL)
  ├── my-metamodel.ttl               ← Manifest (entry point for tools)
  ├── my-tax.ttl                     ← Classification (SKOS)
  ├── my-shapes.ttl                  ← Validation rules (SHACL)
  ├── my-viewpoints.ttl              ← Viewpoint definitions
  ├── my-deliverable-templates.ttl   ← Document templates with SPARQL
  ├── my-reference-data.ttl          ← Controlled vocabularies
  ├── my-presentation-contexts.ttl   ← Stakeholder rendering themes
  └── templates/
      └── *.md.hbs                   ← Handlebars templates for generation

ArchiMate 4.0 has all 13 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 → get all 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)

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 mytax:MyConceptScheme ;
    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.

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)

:MyConceptScheme
    a                skos:ConceptScheme ;
    skos:prefLabel   "My Model Classification"@en ;
    skos:hasTopConcept :BusinessDomain, :TechnologyDomain .

:BusinessDomain
    a skos:Concept ; skos:topConceptOf :MyConceptScheme ;
    skos:prefLabel "Business Domain"@en .

:TechnologyDomain
    a skos:Concept ; skos:topConceptOf :MyConceptScheme ;
    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 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, etc.
  2. Build palette — query element and relationship classes from the ontology, group by SKOS taxonomy
  3. Filter by viewpoint — query arch:includesConcept to restrict the palette per view
  4. Validate — load SHACL shapes, validate on every edit
  5. Render — use arch:prefVisNotation SVG icons for each element type
  6. Generate documents — execute arch:sectionQuery SPARQL, render Handlebars templates
  7. Adapt to stakeholder — switch presentation context to change visual theme
# 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
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
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