Skip to content

Quick Start Guide

This guide walks you through creating a new modeling language metamodel using the Linked.Archi methodology. By the end, you'll have a complete set of semantic artifacts that tools can discover, validate, and render.

Prerequisites

  • Java 17+ (for Turtle syntax validation)
  • Basic familiarity with RDF/Turtle syntax
  • The Linked.Archi repository cloned locally

The Metamodel Pattern

A Linked.Archi metamodel is not a single file — it's a collection of resources tied together by a manifest. Each resource has a specific role:

The Metamodel Pattern A metamodel is a collection of semantic assets tied together by a manifest. Start with just the ontology + manifest.

You don't need all of these to start. The minimum is the ontology + manifest.

Step 1: Create the Ontology

Create modelingLanguages/mymodel/mymodel-onto.ttl:

Convention: Every ontology must declare @prefix : pointing to its own namespace and include the standard header metadata. See DD-14 for the full pattern and rationale.

@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 dc:      <http://purl.org/dc/elements/1.1/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix cc:      <http://creativecommons.org/ns#> .
@prefix vann:    <http://purl.org/vocab/vann/> .
@prefix arch:    <https://meta.linked.archi/core#> .
@prefix :        <https://meta.linked.archi/mymodel#> .

<https://meta.linked.archi/mymodel#>
    rdf:type                      owl:Ontology ;
    owl:imports                   <https://meta.linked.archi/core#> ;
    cc:license                    "http://creativecommons.org/licenses/by/4.0/" ;
    vann:preferredNamespaceUri    "https://meta.linked.archi/mymodel#" ;
    vann:preferredNamespacePrefix "mm" ;
    dc:title                      "My Model Ontology"@en ;
    dc:description                "Elements and relationships for My Model."@en ;
    dcterms:created               "2026-04-16"^^xsd:date ;
    dcterms:modified              "2026-04-16"^^xsd:date ;
    dc:publisher                  "Linked.Archi"@en ;
    owl:versionInfo               "0.1.0" ;
.

## Elements — subclass arch:Element

:Service
    a               owl:Class ;
    rdfs:subClassOf arch:Element ;
    skos:prefLabel  "Service"@en ;
    skos:definition "A service provided to consumers."@en ;
.

:Database
    a               owl:Class ;
    rdfs:subClassOf arch:Element ;
    skos:prefLabel  "Database"@en ;
    skos:definition "A persistent data store."@en ;
.

## Relationships — three declarations each

:dependsOn
    a                    owl:ObjectProperty ;
    skos:prefLabel       "Depends On"@en ;
    skos:definition      "Service depends on another element."@en ;
    arch:domainIncludes  :Service ;
    arch:rangeIncludes   arch:Element ;
.

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

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

Validate: .scripts/validate.sh --syntax modelingLanguages/mymodel/mymodel-onto.ttl

Step 2: Create the Metamodel Manifest

Create modelingLanguages/mymodel/mymodel-metamodel.ttl:

@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix dc:      <http://purl.org/dc/elements/1.1/> .
@prefix arch:    <https://meta.linked.archi/core#> .
@prefix :        <https://meta.linked.archi/mymodel-metamodel#> .

<https://meta.linked.archi/mymodel-metamodel#>
    a owl:Ontology ;
    owl:imports <https://meta.linked.archi/core#> ;
    dc:title "My Model Metamodel Definition"@en ;
.

:MyFramework
    a               arch:Framework ;
    skos:prefLabel  "My Model"@en ;
    skos:definition "Description of the framework."@en ;
.

:MyModelMetamodel
    a                        arch:Metamodel ;
    skos:prefLabel           "My Model Metamodel"@en ;
    arch:basedOnFramework    :MyFramework ;
    arch:modelConcepts       <https://meta.linked.archi/mymodel#> ;
.

That's a working metamodel. Now extend it incrementally.

Step 3: Add a Taxonomy

Create modelingLanguages/mymodel/mymodel-tax.ttl with a SKOS ConceptScheme. Link concepts to OWL classes via rdfs:seeAlso. Then add to the manifest:

arch:conceptClassification  <https://meta.linked.archi/mymodel/tax#> ;

Step 4: Add SHACL Shapes

Create modelingLanguages/mymodel/mymodel-shapes.ttl with NodeShapes for each relationship type. Import core-shapes.ttl. Then add to the manifest:

arch:formalRules  <https://meta.linked.archi/mymodel-shapes#> ;

Step 5: Add Viewpoints

Create modelingLanguages/mymodel/mymodel-viewpoints.ttl with arch:Viewpoint individuals. Each viewpoint specifies: - arch:includesConcept — which element types are allowed - arch:targetsStakeholder — who uses this viewpoint - arch:viewpointFramesConcern — what concerns it addresses - arch:viewpointHasPurpose — Deciding, Designing, Informing, or Governing - arch:viewType — arch:Diagram, arch:Catalog, or arch:Matrix

Then add to the manifest:

arch:architectureViewpoints  <https://meta.linked.archi/mymodel-viewpoints#> ;
arch:viewpointLibrary        mmvp:ViewpointCatalog ;

Step 6: Add Deliverable Templates

Create modelingLanguages/mymodel/mymodel-deliverable-templates.ttl with arch:DeliverableTemplate individuals. Each template specifies which viewpoints are required sections and which presentation formats it supports.

:MyDocument
    a                       arch:DeliverableTemplate ;
    arch:templateRequiresViewpoint mmvp:VP1, mmvp:VP2 ;
    arch:templateHasSection :S1, :S2 ;
    arch:templateTargetsPurpose archvp:Designing ;
    arch:templateHasFormat archdt:MarkdownFormat ;
.

:S1 a arch:TemplateSection ; arch:sectionOrder 1 ;
    arch:sectionViewpoint mmvp:VP1 ;
    skos:prefLabel "1. Section Title"@en .

Then add to the manifest:

arch:hasDeliverableTemplate  :MyDocument ;

Step 7: Add Reference Data and Presentation Contexts

These are SKOS ConceptSchemes for controlled vocabularies and stakeholder rendering themes. See the ArchiMate reference implementation for examples.

Step 8: Validate

# Syntax check all files
.scripts/validate.sh

# SHACL validation (add a profile to validate.sh first)
.scripts/validate.sh --shacl mymodel

Using the Metamodel in a Model

Once the metamodel is defined, models reference it:

ex:MyArchitecture a arch:Model ;
    arch:modelConformsToMetamodel mmmm:MyModelMetamodel ;
    arch:deliverableTemplateUsed mmmm:MyDocument ;
    arch:contains ex:View1, ex:View2 .

ex:View1 a arch:Diagram ;
    arch:viewConformsToViewpoint mmvp:VP1 .

ex:svc1 a mm:Service ;
    skos:prefLabel "Payment Service"@en ;
    arch:exposedInView ex:View1 .

Reference Implementations

Complexity Example Files
Full modelingLanguages/archimate/3.2/ 13 files — all metamodel properties used
Medium modelingLanguages/c4/ 8 files — complete but lighter
Minimal This guide 2 files — onto + manifest

Next Steps