Visual Notation and Palette Generation Guide¶

How Linked.Archi manages visual notation for modeling languages — from type-level defaults to context-aware palette generation.

Overview¶

Linked.Archi separates visual notation into three layers:

Layer	Purpose	Where it lives
VisualNotation + defaultStyle	Type-level construction recipe	`*-notation.ttl` (per modeling language)
prefVisNotation / altVisNotation	Type-level rendered images	On element classes or VisualNotation instances
Style (instance-level)	Per-diagram-element overrides	Model data (user's architecture model)

This separation means: - A palette generator reads the VisualNotation layer to know how to render each concept - A documentation tool reads prefVisNotation to get a quick icon without rendering - A user can override any default via the instance-level Style on their diagram

The Full Flow: PresentationContext → Palette¶

flowchart TD
    User["User selects audience<br/>(role/preference)"]
    PC["<b>PresentationContext</b><br/>e.g., Executive, Architect, Developer<br/><i>SKOS concept in scheme</i>"]
    NS["<b>NotationSet</b><br/>e.g., ArchiMate 4.0 Standard Notation<br/><i>arch-vis:NotationSet</i>"]
    VN["<b>VisualNotation</b> (per concept)<br/>e.g., :BusinessActorNotation<br/><i>arch-vis:VisualNotation</i>"]
    VNdetail["notationFor → am4:BusinessActor<br/>defaultStyle → Style<br/>prefVisNotation → .../business-actor.svg"]
    Style["<b>Style</b> (construction recipe)<br/>shapeType: RoundedRectangle<br/>fillColor: #FFFFB5<br/>lineColor: #000000<br/>iconSymbol: .../person.svg<br/>iconPlacement: TopRight<br/>defaultWidth: 120 · defaultHeight: 55"]

    User --> PC
    PC -->|"arch:usesNotationSet"| NS
    NS -->|"?vn arch-vis:inNotationSet this-set"| VN
    VN --- VNdetail
    VN -->|"arch-vis:defaultStyle"| Style

Fallback Logic¶

If the active PresentationContext has arch:usesNotationSet → use that NotationSet
If not → fall back to arch:notationSet on the Metamodel (the default set)
If a concept has no VisualNotation in the active set → use the element class's arch:prefVisNotation directly

Key Vocabulary¶

In `core-onto.ttl` (arch: namespace)¶

Property	Domain	Range	Purpose
`arch:notationSet`	`arch:Metamodel`	`arch-vis:NotationSet`	Default notation set for the metamodel
`arch:usesNotationSet`	`skos:Concept`	`arch-vis:NotationSet`	Context-specific notation set selection
`arch:prefVisNotation`	`skos:Concept`	`schema:ImageObject`	Rendered composite image (for docs)
`arch:altVisNotation`	`skos:Concept`	`schema:ImageObject`	Alternative rendered images
`arch:presentationContextScheme`	`arch:Metamodel`	`skos:ConceptScheme`	Links to the context scheme

In `core-vis-onto.ttl` (arch-vis: namespace)¶

Class/Property	Type	Purpose
`arch-vis:NotationSet`	Class	Named collection of visual notation descriptors
`arch-vis:VisualNotation`	Class	Descriptor for one ModelConcept's appearance
`arch-vis:Style`	Class	Visual style (extended with shape/icon/mode properties)
`arch-vis:RenderingMode`	Class	How shape and icon are composed (ShapeWithBadge, IconCentric, ShapeOnly)
`arch-vis:notationFor`	Property	Links VisualNotation → ModelConcept
`arch-vis:inNotationSet`	Property	Links VisualNotation → NotationSet
`arch-vis:defaultStyle`	Property	Links VisualNotation → Style (the recipe)
`arch-vis:shapeType`	Property	Geometric shape (on Style)
`arch-vis:iconSymbol`	Property	Icon URI (on Style)
`arch-vis:iconPlacement`	Property	Icon position (on Style)
`arch-vis:renderingMode`	Property	How to compose shape + icon (on Style)
`arch-vis:lineStyle`	Property	Line rendering for relationships
`arch-vis:sourceDecor`	Property	Source endpoint decoration
`arch-vis:targetDecor`	Property	Target endpoint decoration

Enumerations¶

ShapeType: RoundedRectangle, Rectangle, Octagon, Ellipse, Circle, Hexagon, Diamond, Parallelogram

IconPlacement: TopRight, TopLeft, TopCenter, Center, BottomCenter

RenderingMode: ShapeWithBadge, IconCentric, ShapeOnly

LineStyle: SolidLine, DashedLine, DottedLine

Decoration: NoDecoration, OpenArrowhead, ClosedArrowhead, HollowArrowhead, HollowDiamond, FilledDiamond, HalfArrowhead, CircleDot

Rendering Modes¶

The arch-vis:renderingMode property tells a tool how to compose the shape and icon:

Mode	Visual	Use Case
`ShapeWithBadge`	Colored shape + small icon in corner + centered label	ArchiMate standard notation
`IconCentric`	Large icon centered + label below	AWS/Azure/GCP/K8s vendor icons
`ShapeOnly`	Colored shape + centered label, no icon	Simplified/executive views

ShapeWithBadge (ArchiMate default)¶

block-beta
    columns 1
    block:shape1["ShapeWithBadge — ArchiMate default"]
        columns 1
        A["⚙ (top-right badge)&emsp;&emsp;&emsp;&emsp;&emsp;"]
        B["Business Actor (label centered)"]
        C["filled #FFFFB5"]
    end

Colored shape + small icon badge in corner + centered label.

IconCentric (AWS/Azure/GCP)¶

block-beta
    columns 1
    block:shape2["IconCentric — AWS/Azure/GCP"]
        columns 1
        D["☁️ (large icon IS the element)"]
        E["Amazon EC2 (label below)"]
    end

Large icon centered, label below. The icon IS the element.

ShapeOnly (simplified)¶

block-beta
    columns 1
    block:shape3["ShapeOnly — simplified/executive"]
        columns 1
        F["Business Actor (label only)"]
        G["filled #FFFFB5, no icon"]
    end

Colored shape + centered label, no icon.

Rendering Algorithm¶

A tool implementing element rendering MUST select the algorithm based on the arch-vis:renderingMode value on the Style. Here is the pseudocode for each mode:

ShapeWithBadge (default if renderingMode is absent):

function renderShapeWithBadge(element, style):
    shape = drawShape(style.shapeType, style.defaultWidth, style.defaultHeight)
    fill(shape, style.fillColor)
    stroke(shape, style.lineColor)
    centerText(shape, element.prefLabel)

    if style.iconSymbol exists:
        icon = loadSVG(style.iconSymbol)
        resizeIcon(icon, 16px or 24px)          // small badge size
        placeIcon(icon, shape, style.iconPlacement)  // e.g., TopRight

IconCentric:

function renderIconCentric(element, style):
    if style.iconSymbol is missing:
        LOG WARNING "IconCentric requires iconSymbol"
        return renderShapeOnly(element, style)   // fallback

    icon = loadSVG(style.iconSymbol)
    resizeIcon(icon, style.defaultWidth, style.defaultHeight)  // full size
    drawCentered(icon)

    // optional: minimal container for selection/hover
    border = drawShape(Rectangle, style.defaultWidth + padding, style.defaultHeight + padding)
    stroke(border, style.lineColor)
    fill(border, style.fillColor or transparent)

    drawTextBelow(icon, element.prefLabel)       // label BELOW, not inside

ShapeOnly:

function renderShapeOnly(element, style):
    shape = drawShape(style.shapeType, style.defaultWidth, style.defaultHeight)
    fill(shape, style.fillColor)
    stroke(shape, style.lineColor)
    centerText(shape, element.prefLabel)
    // NO icon rendering — ignore iconSymbol and iconPlacement entirely

Fallback Rules¶

Condition	Behavior
`renderingMode` absent on Style	Default to `ShapeWithBadge`
`renderingMode` is `ShapeWithBadge` but `iconSymbol` absent	Render as `ShapeOnly` (graceful degradation)
`renderingMode` is `IconCentric` but `iconSymbol` absent	Log warning, fall back to `ShapeOnly`
`iconPlacement` absent but `iconSymbol` present	Default to `TopRight`

When to Use Each Mode¶

Mode	Use When	Examples
`ShapeWithBadge`	The modeling language has a formal notation with colored shapes and small classifier icons	ArchiMate, BPMN, UML
`IconCentric`	The visual identity comes from vendor/product icons that users recognize instantly	AWS Architecture Icons, Azure service icons, GCP icons, Kubernetes
`ShapeOnly`	Simplicity is preferred — executive presentations, monochrome printing, high-level overviews	Executive dashboards, printed reports, accessibility-focused views

Vendor Icon Sets (AWS, Azure, GCP)¶

To use vendor icons (AWS Architecture Icons, Azure service icons, etc.), create a notation set with IconCentric rendering mode:

@prefix arch:     <https://meta.linked.archi/core#> .
@prefix arch-vis: <https://meta.linked.archi/core-vis#> .
@prefix am4:      <https://meta.linked.archi/archimate4/onto#> .
@prefix myonto:   <https://meta.linked.archi/mymodel/onto#> .
@prefix :         <https://meta.linked.archi/mymodel/notation-aws#> .

:AWSIconNotation
    a               arch-vis:NotationSet ;
    skos:prefLabel  "AWS Architecture Icons"@en ;
    skos:definition "Renders elements using official AWS Architecture Icon set."@en .

## EC2 Instance (extends am4:Node or a custom class)
:EC2Notation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor myonto:EC2Instance ;
    arch-vis:inNotationSet :AWSIconNotation ;
    arch:prefVisNotation  <https://meta.linked.archi/aws/icons/ec2-composed.svg> ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        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:fillColor     "#FFFFFF" ;
        arch-vis:lineColor     "#232F3E" ;
        arch-vis:defaultWidth  64.0 ;
        arch-vis:defaultHeight 64.0 ;
    ] .

## S3 Bucket
:S3Notation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor myonto:S3Bucket ;
    arch-vis:inNotationSet :AWSIconNotation ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        arch-vis:renderingMode arch-vis:IconCentric ;
        arch-vis:iconSymbol    "https://d1.awsstatic.com/icons/Arch_Amazon-S3_64.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:Center ;
        arch-vis:fillColor     "#FFFFFF" ;
        arch-vis:lineColor     "#3F8624" ;
        arch-vis:defaultWidth  64.0 ;
        arch-vis:defaultHeight 64.0 ;
    ] .

## Lambda Function
:LambdaNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor myonto:LambdaFunction ;
    arch-vis:inNotationSet :AWSIconNotation ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        arch-vis:renderingMode arch-vis:IconCentric ;
        arch-vis:iconSymbol    "https://d1.awsstatic.com/icons/Arch_AWS-Lambda_64.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:Center ;
        arch-vis:fillColor     "#FFFFFF" ;
        arch-vis:lineColor     "#D86613" ;
        arch-vis:defaultWidth  64.0 ;
        arch-vis:defaultHeight 64.0 ;
    ] .

Then link it to a PresentationContext:

## Developers see AWS icons, architects see ArchiMate notation
mypc:DeveloperContext
    arch:usesNotationSet <https://meta.linked.archi/mymodel/notation-aws#AWSIconNotation> .

mypc:ArchitectContext
    arch:usesNotationSet am4not:ArchiMate40StandardNotation .

The same model, two views: An architect sees rounded rectangles with ArchiMate icons. A developer sees AWS service icons. The underlying RDF data is identical — only the visual rendering changes based on the active PresentationContext.

Example: ArchiMate 4.0¶

Metamodel manifest links to the notation set¶

## In archimate4-metamodel.ttl
:ArchiMate4
    arch:notationSet              am4not:ArchiMate40StandardNotation ;
    arch:presentationContextScheme am4pc:ArchiMatePresentationContexts ;
.

PresentationContext links to the notation set¶

## In archimate4-presentation-contexts.ttl
am4pc:ArchitectContext
    arch:usesNotationSet am4not:ArchiMate40StandardNotation .

am4pc:ExecutiveContext
    arch:usesNotationSet am4not:ArchiMate40SimplifiedNotation .

VisualNotation defines the appearance¶

## In archimate4-notation.ttl
:BusinessActorNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor am4:BusinessActor ;
    arch-vis:inNotationSet :ArchiMate40StandardNotation ;
    arch:prefVisNotation  <https://meta.linked.archi/archimate4/icons/business-actor.svg> ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        arch-vis:shapeType     arch-vis:RoundedRectangle ;
        arch-vis:fillColor     "#FFFFB5" ;
        arch-vis:lineColor     "#000000" ;
        arch-vis:iconSymbol    "https://meta.linked.archi/archimate4/icons/glyphs/person.svg"^^xsd:anyURI ;
        arch-vis:iconPlacement arch-vis:TopRight ;
        arch-vis:defaultWidth  120.0 ;
        arch-vis:defaultHeight 55.0 ;
    ] ;
.

Relationship notation (on the relationship class)¶

## In archimate4-notation.ttl
:ServingNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor am4:Serving ;
    arch-vis:inNotationSet :ArchiMate40StandardNotation ;
    arch-vis:lineStyle    arch-vis:SolidLine ;
    arch-vis:sourceDecor  arch-vis:NoDecoration ;
    arch-vis:targetDecor  arch-vis:OpenArrowhead ;
.

SPARQL: Palette Generation Query¶

PREFIX arch:     <https://meta.linked.archi/core#>
PREFIX arch-vis: <https://meta.linked.archi/core-vis#>
PREFIX skos:     <http://www.w3.org/2004/02/skos/core#>
PREFIX am4not:   <https://meta.linked.archi/archimate4/notation#>

# Get all element notations for the standard notation set
SELECT ?concept ?label ?shape ?fill ?icon ?iconPos ?renderMode ?width ?height ?image
WHERE {
    ?vn a arch-vis:VisualNotation ;
        arch-vis:inNotationSet am4not:ArchiMate40StandardNotation ;
        arch-vis:notationFor ?concept ;
        arch-vis:defaultStyle ?style .

    ?concept skos:prefLabel ?label .
    FILTER(lang(?label) = "en")

    ?style arch-vis:shapeType ?shape ;
           arch-vis:fillColor ?fill ;
           arch-vis:defaultWidth ?width ;
           arch-vis:defaultHeight ?height .

    OPTIONAL { ?style arch-vis:renderingMode ?renderMode }
    OPTIONAL { ?style arch-vis:iconSymbol ?icon }
    OPTIONAL { ?style arch-vis:iconPlacement ?iconPos }
    OPTIONAL { ?vn arch:prefVisNotation ?image }
}
ORDER BY ?label

Creating Alternative Notation Sets¶

To create a simplified notation for executives:

Create a new file (e.g., archimate4-notation-simplified.ttl)
Define a new NotationSet individual
Create VisualNotation instances with simpler styles (no icons, flat colors)
Link the PresentationContext to the new set

:ArchiMate40SimplifiedNotation
    a               arch-vis:NotationSet ;
    skos:prefLabel  "ArchiMate 4.0 Simplified Notation"@en ;
    skos:definition "Simplified notation for executive presentations — flat shapes, no icons."@en ;
.

:BusinessActorSimplifiedNotation
    a                    arch-vis:VisualNotation ;
    arch-vis:notationFor am4:BusinessActor ;
    arch-vis:inNotationSet :ArchiMate40SimplifiedNotation ;
    arch-vis:defaultStyle [
        a                      arch-vis:Style ;
        arch-vis:shapeType     arch-vis:RoundedRectangle ;
        arch-vis:fillColor     "#FFFFB5" ;
        arch-vis:lineColor     "#666666" ;
        ## No icon — simplified
        arch-vis:defaultWidth  100.0 ;
        arch-vis:defaultHeight 40.0 ;
    ] ;
.

Then update the PresentationContext:

am4pc:ExecutiveContext
    arch:usesNotationSet am4not:ArchiMate40SimplifiedNotation .

Regenerating Notation Files¶

The notation TTL files and SVG icons are static authored assets maintained alongside the ontology files. They are not generated from an external source — edit them directly when adding elements or changing visual properties.

C4 and EDGY notation files and icons are maintained in their respective directories: - modelingLanguages/c4/c4-notation.ttl + modelingLanguages/c4/icons/ - modelingLanguages/edgy/edgy-notation.ttl + modelingLanguages/edgy/icons/

SVG icons live alongside the notation TTL files in the modeling language directory so they are committed to the repository and deployed by the CI pipeline.

Deployment and URI Resolution¶

Icon URIs in the notation files reference the published site (e.g., https://meta.linked.archi/archimate4/icons/business-actor.svg). The CI pipeline copies icons from their source locations into the deployed site using .scripts/copy-icon-assets.sh:

Source path	Deployed to	URI prefix
`core/icons/markers/`	`public/core-vis/markers/`	`https://meta.linked.archi/core-vis/markers/`
`modelingLanguages/archimate/4.0/icons/`	`public/archimate4/icons/`	`https://meta.linked.archi/archimate4/icons/`
`modelingLanguages/archimate/3.2/icons/`	`public/archimate3/icons/`	`https://meta.linked.archi/archimate3/icons/`
`modelingLanguages/c4/icons/`	`public/c4/icons/`	`https://meta.linked.archi/c4/icons/`
`modelingLanguages/edgy/icons/`	`public/edgy/icons/`	`https://meta.linked.archi/edgy/icons/`

This applies to both GitLab Pages and the server deployment (both use the same public/ artifact).

For local/offline use, resolve https://meta.linked.archi/ to the repo root — e.g., https://meta.linked.archi/archimate4/icons/business-actor.svg maps to modelingLanguages/archimate/4.0/icons/business-actor.svg.

References¶

Core Ontology Reference — Full property and class documentation
ArchiMate README — ArchiMate-specific files and namespaces
Design Decisions — Modeling decisions and rationale