Skip to content

Cloud Platform Metamodel — A Complete Walkthrough

This walkthrough explains the design decisions behind the Cloud Platform Architecture example in examples/custom-metamodel/. It follows the same 8 steps as the Build Your Own Metamodel guide, but with full rationale for each choice and guidance on how to adapt the patterns for your own organization.

The example extends ArchiMate 4.0 with cloud-native concepts — microservices, containers, message brokers, and Kubernetes clusters. The result is a complete metamodel that a modeling tool can consume.

The Scenario

A platform engineering team needs to model their cloud-native payment platform. ArchiMate 4.0 provides the foundation (ApplicationComponent, Node, DataObject, etc.) but lacks cloud-specific concepts. The team needs:

  • Microservice as a distinct element type (not just a generic ApplicationComponent)
  • Container and KubernetesCluster for deployment modeling
  • MessageBroker and EventTopic for event-driven communication
  • Custom properties like resilience level, deployment strategy, and service tier
  • Custom relationships like publishesTo and subscribesTo
  • Validation rules that enforce organizational standards (e.g., critical services must be tier-1)
  • Document generation from the model (service catalog, deployment guide)

Step 1: Elements — What to Subclass and Why

File: cloudplatform-onto.ttl

Design Decision: Extend ArchiMate, Don't Replace It

Every custom element subclasses an ArchiMate 4.0 type:

Custom Element Extends Why
cp:Microservice am4:ApplicationComponent A microservice is an application component with additional properties. ArchiMate relationships (serves, accesses, assignedTo) still apply.
cp:APIGateway am4:ApplicationComponent Same reasoning — it's a specialized component.
cp:Container am4:Node A container is a deployment node. ArchiMate's deployment relationships work.
cp:KubernetesCluster am4:Node A cluster is infrastructure.
cp:MessageBroker am4:ApplicationComponent A broker is an application-level component, not infrastructure.
cp:EventTopic am4:DataObject A topic is a data channel — it carries information, like a DataObject.
cp:ManagedDatabase am4:ApplicationComponent A managed DB is a cloud service (application-level), not raw infrastructure.
cp:CacheStore am4:ApplicationComponent Same — Redis is a service, not a node.
cp:ObservabilityStack am4:ApplicationComponent Prometheus/Grafana is a service stack.

Why not am4:SystemSoftware for databases? Because managed databases (RDS, Cloud SQL) are cloud services, not software you install on a node. If you're modeling self-hosted PostgreSQL on bare metal, am4:SystemSoftware would be correct. The choice depends on your deployment model.

How to adapt: Replace these elements with your organization's concepts. A retail company might add PointOfSaleTerminal, InventorySystem, SupplyChainHub. A healthcare company might add ClinicalSystem, PatientPortal, HL7Interface.

Design Decision: Custom Properties Use arch:domainIncludes

Properties like cp:resilienceLevel use arch:domainIncludes (guidance) rather than rdfs:domain (inference). This follows DD-6 — we want tools to suggest valid connections, not reasoners to infer types. See the Domain & Range Guide for the full rationale.

Design Decision: Three-Declaration Relationships

Custom relationships (publishesTo, subscribesTo, deployedIn) follow the three-declaration pattern from DD-3:

  1. Unqualified predicate (cp:publishesTo) — for SPARQL traversal
  2. Qualified class (cp:Publishing) — for metadata, lifecycle, provenance
  3. Qualified predicate (cp:qualifiedPublishesTo) — for navigation from source to qualified node

Why not just use am4:flowsTo? Because publishesTo and subscribesTo carry specific semantics — they're directional, they imply asynchronous communication, and they connect to specific topics. am4:flowsTo is generic. Custom relationships make the model more precise and queryable.

Step 2: Metamodel Manifest — The Entry Point

File: cloudplatform-metamodel.ttl

The manifest is small but critical — it's the single IRI a tool loads to discover everything:

:CloudPlatformMetamodel
    a                             arch:Metamodel ;
    arch:modelConcepts            <.../cloudplatform/onto#> ;
    arch:formalRules              <.../cloudplatform/shapes#> ;
    arch:architectureViewpoints   <.../cloudplatform/viewpoints#> ;
    arch:conceptClassification    cptax:CloudPlatformScheme ;
    arch:hasDeliverableTemplate   cpdt:ServiceCatalog, cpdt:DeploymentGuide ;
    arch:referenceData            cpref:CloudPlatformReferenceData .

A tool that understands arch:Metamodel can bootstrap from this single resource — load the ontology for the palette, the shapes for validation, the viewpoints for filtering, the taxonomy for grouping, and the templates for generation.

Step 3: Taxonomy — Palette Organization

File: cloudplatform-tax.ttl

The taxonomy groups elements into 5 categories for the modeling palette:

  • Runtime Services — Microservice, APIGateway
  • Data Services — ManagedDatabase, CacheStore
  • Integration Services — MessageBroker, EventTopic
  • Observability — ObservabilityStack
  • Infrastructure — Container, KubernetesCluster

The link between OWL classes and SKOS concepts uses rdfs:seeAlso:

cp:Microservice rdfs:seeAlso cptax:RuntimeServices .

How to adapt: Organize by whatever dimension makes sense for your architects. Some organizations group by domain (Customer, Order, Payment). Others by team (Platform, Backend, Frontend). The taxonomy is independent of the ontology — you can have multiple taxonomies for different audiences.

Step 4: SHACL Shapes — What Gets Validated

File: cloudplatform-shapes.ttl

Three categories of shapes:

Required Properties

Every Microservice must have a name and resilience level. Every Container must have an image and replica count. These catch incomplete model data.

Relationship Constraints

Publishing source must be a Microservice, target must be an EventTopic. These prevent invalid connections.

Governance Principles

Critical microservices should have tier-1 SLA (warning, not error). Every microservice should have a container deployment (warning). These encode organizational standards as executable rules.

How to adapt: Add your organization's governance rules. Examples: - "Every application must have an owner" → sh:property [ sh:path arch:conceptOwner ; sh:minCount 1 ] - "No direct database access from external services" → SPARQL-based shape - "Every API must have documentation" → sh:property [ sh:path schema:documentation ; sh:minCount 1 ]

Step 5: Viewpoints — What Goes in Which View

File: cloudplatform-viewpoints.ttl

Four viewpoints, each for a different audience:

Viewpoint Audience Elements Included Purpose
Service Dependency Architect, Developer Microservice, APIGateway, MessageBroker, EventTopic + relationships Design service interactions
Deployment Platform Engineer, SRE Microservice, Container, KubernetesCluster + deployment Plan infrastructure
Data Flow Architect, Developer Microservice, Database, Cache, EventTopic + access/flow Understand data movement
Platform Overview Architect All major components Executive communication

When a tool opens a "Service Dependency View", it queries arch:includesConcept and filters the palette to only show the allowed element types. This prevents architects from accidentally adding infrastructure elements to a service dependency diagram.

Step 6: Deliverable Templates — Generate Documents from the Graph

Files: cloudplatform-deliverable-templates.ttl, templates/*.md.hbs

Two documents, each with SPARQL queries that extract data from the model:

Service Catalog

  • Section 1: Service inventory (name, resilience, tier, strategy)
  • Section 2: Event-driven dependencies (publisher → topic → subscriber)
  • Section 3: Deployment status (service → container → image → replicas → cluster)

Deployment Guide

  • Section 1: Kubernetes clusters with container counts
  • Section 2: Container inventory with images and replicas

Each section has a arch:sectionQuery (SPARQL SELECT) and a arch:sectionResultKey (JSON key). The generator executes the queries, assembles a JSON context, and renders the Handlebars template.

How to adapt: Add templates for your organization's deliverables — architecture review documents, compliance reports, onboarding guides. The SPARQL queries can extract any data from the model.

Step 7: Reference Data — Controlled Vocabularies

File: cloudplatform-reference-data.ttl

Four vocabularies: - Resilience Levels — Critical, High, Medium, Low (with definitions) - Deployment Strategies — Blue-Green, Canary, Rolling, Recreate - Service Tiers — Tier 1 (99.99%), Tier 2 (99.9%), Tier 3 (99%) - Database Engines — PostgreSQL, MySQL, MongoDB, Redis

These are SKOS ConceptSchemes that tools can use for dropdown menus and validation. The SHACL shapes reference the same values via sh:in.

The Example Model — Putting It All Together

File: example-model.ttl

A payment platform with: - 5 microservices (Order, Payment, Notification, Fraud Detection, Reporting) - 1 API gateway (Kong) - 2 managed databases (Orders, Payments — both PostgreSQL) - 1 cache (Redis) - 1 message broker (Kafka) with 3 event topics - 1 observability stack (Prometheus + Grafana + Jaeger) - 1 Kubernetes cluster with 5 containers

The model uses both ArchiMate relationships (am4:serves, am4:accesses, am4:assignedTo) and custom relationships (cp:publishesTo, cp:subscribesTo, cp:deployedIn). This demonstrates that extending ArchiMate doesn't break existing relationships — it adds new ones alongside them.

Querying the Model

# Which services publish to topics that the Fraud Detection service subscribes to?
PREFIX cp: <https://meta.linked.archi/examples/cloudplatform/onto#>

SELECT ?publisher ?publisherLabel ?topic ?topicLabel WHERE {
    ?publisher cp:publishesTo ?topic .
    <https://model.example.com/payment-platform#FraudDetectionService> cp:subscribesTo ?topic .
    ?publisher skos:prefLabel ?publisherLabel .
    ?topic skos:prefLabel ?topicLabel .
}

# Which critical services have fewer than 3 replicas?
PREFIX cp: <https://meta.linked.archi/examples/cloudplatform/onto#>
PREFIX am4: <https://meta.linked.archi/archimate4/onto#>

SELECT ?service ?label ?replicas WHERE {
    ?service a cp:Microservice ;
             skos:prefLabel ?label ;
             cp:resilienceLevel "critical" .
    ?container am4:assignedTo ?service ;
               cp:replicaCount ?replicas .
    FILTER(?replicas < 3)
}

Adapting for Your Organization

If your domain is... Replace these elements With these
Retail Microservice, MessageBroker PointOfSaleSystem, InventoryService, SupplyChainConnector
Healthcare Microservice, EventTopic ClinicalSystem, PatientPortal, HL7Interface, FHIREndpoint
Finance Container, KubernetesCluster TradingEngine, RiskCalculator, MarketDataFeed
Government APIGateway, ObservabilityStack CitizenPortal, InteragencyBus, AuditLogger

The patterns are the same — subclass ArchiMate elements, add domain-specific properties, define SHACL validation, create viewpoints for your stakeholders, and build deliverable templates for your documents.

References