Names, Labels and Pictures per Presentation Context¶

A presentation context is an audience: executives, architects, developers, operations. A metamodel lists its audiences in a SKOS scheme (arch:presentationContextScheme), and a modelling tool lets the reader pick one. These things follow the context the reader picked:

What follows the context	Said with	Where	Example
How every element of a kind looks	`arch:usesNotationSet` → an `arch-vis:NotationSet`	On the context	Executives see a simplified notation
What an element is called	A SKOS-XL name with `arch:inPresentationContext`	On the element, in the model	Executives read "Card payments"; developers read `pgw-svc`
What an element's picture is	`arch:altVisNotation` → a `schema:ImageObject` with `arch:inPresentationContext`	On the element, in the model	Executives see the card-payments logo
What its diagram label says	An `arch-vis:LabelExpression` with `arch:inPresentationContext`	On a diagram element, a notation, or the context	Architects see the type under each name
How one diagram element looks	An `arch-vis:Style` with `arch:inPresentationContext`	On the diagram element	Executives see the gateway as its picture; developers as a box with a picture inside

One pattern runs through all but the first: several values, each for one context (arch:inPresentationContext) or — without it — for every context, at most one per context; for a context, the one for it wins over the one for every context.

The look of every element of a kind is covered in the Visual Notation Guide. Every case below is in one file, examples/labels-per-presentation.ttl, with what each element shows in each context; the core-vis validation profile checks it. Why it is designed this way: DD-34 (names and labels) and DD-35 (pictures and looks).

Prefixes used on this page:

@prefix skos:     <http://www.w3.org/2004/02/skos/core#> .
@prefix skosxl:   <http://www.w3.org/2008/05/skos-xl#> .
@prefix dcterms:  <http://purl.org/dc/terms/> .
@prefix arch:     <https://meta.linked.archi/core#> .
@prefix arch-vis: <https://meta.linked.archi/core-vis#> .
@prefix am:       <https://meta.linked.archi/archimate3/onto#> .
@prefix am4pc:    <https://meta.linked.archi/archimate4/presentation-contexts#> .
@prefix am4not:   <https://meta.linked.archi/archimate4/notation#> .
@prefix schema:   <http://schema.org/> .
@prefix xsd:      <http://www.w3.org/2001/XMLSchema#> .
@prefix ex:       <https://example.org/model/> .

Presentation contexts¶

A metamodel names its scheme of contexts; each context is a skos:Concept in it, and names the notation set it is drawn with:

am4pc:DeveloperContext
    a                    skos:Concept ;
    skos:inScheme        am4pc:ArchiMatePresentationContexts ;
    skos:prefLabel       "Developer / Engineering"@en ;
    arch:usesNotationSet am4not:ArchiMate40StandardNotation .

Several contexts may use the same notation set — every ArchiMate context uses the standard one. Names and labels are scoped to the context, not to its notation set, so audiences that share a look can still read different names and labels.

When no context is picked, only what is said for every context applies.

Names for an audience (SKOS-XL)¶

The canonical name¶

An element's canonical name is its skos:prefLabel, language tagged, one per language. Every tool reads it, whatever the audience. Nothing on this page changes that.

A name for one audience¶

A name for one audience is a SKOS-XL label: a resource of its own, so that it can say which context it is for.

ex:paymentGateway
    a               am:ApplicationComponent ;
    skos:prefLabel  "Payment gateway"@en ;                       # canonical, for everyone
    skosxl:altLabel ex:paymentGateway-name-developer ,
                    ex:paymentGateway-name-executive ;
    skos:altLabel   "pgw-svc"@en, "Card payments"@en .           # the same names, as plain SKOS

ex:paymentGateway-name-developer
    a                          skosxl:Label ;
    skosxl:literalForm         "pgw-svc"@en ;
    arch:inPresentationContext am4pc:DeveloperContext .

ex:paymentGateway-name-executive
    a                          skosxl:Label ;
    skosxl:literalForm         "Card payments"@en ;
    arch:inPresentationContext am4pc:ExecutiveContext .

The rules:

skosxl:altLabel, never skosxl:prefLabel. SKOS-XL makes every skosxl:prefLabel a skos:prefLabel too, and an element has one skos:prefLabel per language: its canonical name. A preferred label per audience would give it several canonical names.
Also a plain skos:altLabel. Write the label's literal form as the element's skos:altLabel as well — what SKOS-XL itself entails — so tools that read plain SKOS (search, documentation, converters) still find it as one of the element's names.
One literal form, language tagged. "pgw-svc"@en, not "pgw-svc".
At most one name per context and language. An element may have an English and a German name for developers, not two English ones.
A name without arch:inPresentationContext is for every audience: a SKOS-XL alternative name like any other.

Give the label an IRI of its own — the element's IRI with -name- and the context, say — rather than a blank node: models kept in Git are merged triple by triple, and a blank node cannot be matched across versions.

Reading names for an audience¶

The name an element has for a context — its name for that context, else its canonical name:

PREFIX skos:   <http://www.w3.org/2004/02/skos/core#>
PREFIX skosxl: <http://www.w3.org/2008/05/skos-xl#>
PREFIX arch:   <https://meta.linked.archi/core#>
PREFIX am4pc:  <https://meta.linked.archi/archimate4/presentation-contexts#>

SELECT ?element ?name WHERE {
  ?element skos:prefLabel ?canonical .
  FILTER(LANG(?canonical) = "en")
  OPTIONAL {
    ?element skosxl:altLabel ?label .
    ?label arch:inPresentationContext am4pc:DeveloperContext ;
           skosxl:literalForm ?forContext .
    FILTER(LANG(?forContext) = "en")
  }
  BIND(COALESCE(?forContext, ?canonical) AS ?name)
}

Pictures for an audience¶

An element's own picture — a logo, a product image — is its arch:prefVisNotation: the picture for every audience. A picture for one audience is an arch:altVisNotation whose value is a schema:ImageObject, its address in schema:contentUrl and its audience in arch:inPresentationContext — the way a name for one audience is a SKOS-XL label.

ex:paymentGateway
    arch:prefVisNotation ex:paymentGateway-picture ;
    arch:altVisNotation  ex:paymentGateway-picture-executive .

ex:paymentGateway-picture
    a                 schema:ImageObject ;
    schema:contentUrl "https://example.org/pictures/gateway.svg"^^xsd:anyURI .

ex:paymentGateway-picture-executive
    a                          schema:ImageObject ;
    schema:contentUrl          "https://example.org/pictures/card-payments.png"^^xsd:anyURI ;
    arch:inPresentationContext am4pc:ExecutiveContext .

The rules:

schema:contentUrl is an xsd:anyURI: an http(s) URL, or a data:image/… URI for a small picture kept in the model.
A value may also be the image's own IRI, as published notations write arch:prefVisNotation; readers accept both. One for an audience is an ImageObject, since an image's own IRI cannot say which audience it is for.
At most one picture per context. An arch:altVisNotation without a context is an alternative for no particular audience; an arch:prefVisNotation is never for one.
Give the ImageObject an IRI of its own (the element's IRI with -picture- and the context, say), for the same reason as a name.

The picture for a context — its arch:altVisNotation for that context, else its arch:prefVisNotation:

PREFIX schema: <http://schema.org/>
PREFIX arch:   <https://meta.linked.archi/core#>
PREFIX am4pc:  <https://meta.linked.archi/archimate4/presentation-contexts#>

SELECT ?element ?picture WHERE {
  OPTIONAL {
    ?element arch:altVisNotation ?forContext .
    ?forContext arch:inPresentationContext am4pc:ExecutiveContext ; schema:contentUrl ?contextUrl .
  }
  OPTIONAL {
    ?element arch:prefVisNotation ?canonical .
    OPTIONAL { ?canonical schema:contentUrl ?canonicalUrl }
  }
  FILTER(BOUND(?contextUrl) || BOUND(?canonical))
  BIND(COALESCE(?contextUrl, ?canonicalUrl, STR(?canonical)) AS ?picture)
}

How a picture is drawn on a diagram: Where an element's picture is drawn.

What a label says (label expressions)¶

Without anything else, a diagram element's label is the element's name for the context shown. A label expression says more: text with placeholders between braces, each line of it a line of the label.

[] a                   arch-vis:LabelExpression ;
   arch-vis:expression "{name}\n«{type}»" .

Placeholders¶

Placeholder	Shows	Example result
`{name}`	The element's name for the context shown: its SKOS-XL name for that context, else its `skos:prefLabel`	`pgw-svc` (developer), `Payment gateway` (architect)
`{type}`	The name of its type	`Application Component`
`{prefix:local}`	The values of that property of the element	`{dcterms:creator}` → `Ana`
`{<iri>}`	The same, the property by its full IRI	`{<http://purl.org/dc/terms/creator>}` → `Ana`
`{skos:prefLabel}`	Its canonical name, whatever the context — a property like any other	`Payment gateway`
`{a/b}`	A path: `a` followed from the element, then `b` from what that gives	`{am:assignedTo/skos:prefLabel}`
`{^a}`	A property followed backwards: what has the element as its value of `a`	`{^arch:target}` → the relationships ending at it
`{^arch:source/arch:target}`	Both: the relationships starting at it, then their targets	`serves Checkout` (with text around it)
`{{` and `}}`	A brace	`{{draft}}` → `{draft}`

How values are shown:

A literal as it is — in the language shown, or one with no language; with neither, any.
A resource by its name for the context shown (its SKOS-XL name there, else its skos:prefLabel), or by the last part of its IRI when it has no name.
Several values joined by ", ", each once.
Prefixes are the common ones (arch, arch-vis, skos, dcterms, rdf, rdfs, owl, …), those the vocabularies in use declare (vann:preferredNamespacePrefix: am, am4, c4, …) and the model's own.

Lines¶

The expression's lines are the label's lines. A line whose placeholders all come to nothing is left out, so a line can be there only when the element has what it shows:

{name}
by {dcterms:creator}

shows Checkout / by Bo for an element with a creator, and just Checkout for one without. A line with no placeholder at all is always shown.

What cannot be read¶

A placeholder that cannot be read — an unknown prefix, a path ending with /, nothing between the braces — is drawn as it was written, so that the mistake shows, and a tool says what is wrong with it. A { that is never closed is text.

Where a label expression is said¶

An expression is given with arch-vis:labelExpression, in one of three places. At each, an expression with arch:inPresentationContext is for that context alone; one without it is for every context.

1. A diagram element's own style — that element only¶

ex:gatewayNode
    a                    arch-vis:ArchNode ;
    arch-vis:archElement ex:paymentGateway ;
    arch-vis:style       ex:gatewayNodeStyle .

ex:gatewayNodeStyle
    a                        arch-vis:Style ;
    arch-vis:labelExpression ex:gatewayForDevelopers, ex:gatewayForEveryone .

ex:gatewayForDevelopers
    a                          arch-vis:LabelExpression ;
    arch:inPresentationContext am4pc:DeveloperContext ;
    arch-vis:expression        "{name} ({skos:prefLabel})\nserves {^arch:source/arch:target}" .

ex:gatewayForEveryone
    a                   arch-vis:LabelExpression ;
    arch-vis:expression "{name}" .

Another placement of the same element, in this view or another, keeps its own.

2. A concept's notation — every element of that concept¶

On its arch-vis:VisualNotation, or on the notation's arch-vis:defaultStyle:

am4not:ApplicationComponentNotation
    arch-vis:labelExpression [
        a                          arch-vis:LabelExpression ;
        arch:inPresentationContext am4pc:ArchitectContext ;
        arch-vis:expression        "{name}\n«{type}»"
    ] , [
        a                   arch-vis:LabelExpression ;
        arch-vis:expression "{name}"
    ] .

A concept with no notation of its own takes its nearest superclass's, as it does for its look.

3. A presentation context — everything shown in it¶

am4pc:DeveloperContext
    arch-vis:labelExpression [
        a                   arch-vis:LabelExpression ;
        arch-vis:expression "{name}\nby {dcterms:creator}"
    ] .

An expression on a context needs no arch:inPresentationContext: it is that context's.

Which one applies¶

The first that applies wins:

the diagram element's own, for the context shown;
the diagram element's own, for every context;
its concept's notation's, for the context shown;
its concept's notation's, for every context;
the context's;
none — the label is the element's name for the context shown.

In examples/labels-per-presentation.ttl, three elements in three contexts:

Element	Architect	Developer	Executive
Payment gateway — its own expressions: one for developers, one for every context	`Payment gateway` (2)	`pgw-svc (Payment gateway)` / `serves Checkout` (1)	`Card payments` (2: `{name}` is the executive name)
Ledger — none of its own; an application component's notation has one for architects and one for every context	`Ledger` / `«Application Component»` (3)	`Ledger` (4, before the context's)	`Ledger` (4)
Checkout — none of its own, none in an application service's notation	`Checkout` (6)	`Checkout` / `by Bo` (5)	`Checkout` (6)

A context with no label expression and no names still changes nothing; one that only names a notation set changes the look alone.

A diagram element's look per context¶

A diagram element's arch-vis:style says how it looks: its colours, its font, its figure (arch-vis:renderingMode, arch-vis:shapeType), its own icon (arch-vis:iconSymbol), a picture inside it (arch-vis:image, arch-vis:imagePosition). It may have one style for every context and one for each context; drawn for a context, the style for that context is laid over the style for every context, value by value. Drawn for no context, it has its style for every context alone.

ex:gatewayNode
    arch-vis:style ex:gatewayNode-style, ex:gatewayNode-style-executive, ex:gatewayNode-style-developer .

ex:gatewayNode-style                       # every context: a blue box
    a                  arch-vis:Style ;
    arch-vis:fillColor "#b5c9ff" .

ex:gatewayNode-style-executive             # executives: the element's picture as the figure
    a                          arch-vis:Style ;
    arch:inPresentationContext am4pc:ExecutiveContext ;
    arch-vis:renderingMode     arch-vis:IconCentric .

ex:gatewayNode-style-developer             # developers: the blue box, a picture inside at the bottom right
    a                          arch-vis:Style ;
    arch:inPresentationContext am4pc:DeveloperContext ;
    arch-vis:image             "https://example.org/pictures/postgres.svg"^^xsd:anyURI ;
    arch-vis:imagePosition     arch-vis:BottomRight .

A diagram element with a single style — any written before this — looks the same to everyone.

Where an element's picture is drawn¶

An element's picture is drawn where the diagram element is drawn as its icon (arch-vis:IconCentric): by its notation (a vendor icon set), or by its own style for the context shown. The icon is, in this order:

the arch-vis:iconSymbol of the diagram element's own style (for the context shown, else for every context);
its element's picture for the context shown — its arch:altVisNotation for that context, else its arch:prefVisNotation;
its notation's glyph.

In box-with-badge mode (arch-vis:ShapeWithBadge) the badge stays the notation's glyph, which says the element's type. A picture inside the box, on one diagram element only, is its style's arch-vis:image.

Diagram element in `examples/labels-per-presentation.ttl`	Architect	Developer	Executive
The gateway — a style for every context, one for executives drawing it as its icon	A box, the notation's glyph as its badge	The same	Its executive picture as the figure, "Card payments" under it
The ledger — a style for developers only, with a picture inside	A box	A box, `postgres.svg` at its bottom right	A box

Names and labels together¶

With no label expression, the label is {name}: switching context switches the names drawn.
{name} and the names of resources a placeholder shows are names for the context shown.
{skos:prefLabel} is the canonical name, whatever the context: {name} ({skos:prefLabel}) shows both.
Renaming an element changes its canonical name. A name for an audience is changed where the names are kept.

Validation¶

Rule	Shape	Severity
A SKOS-XL label has exactly one `skosxl:literalForm`, language tagged	`archsh:PresentationNameShape` (core shapes)	Violation
A SKOS-XL label is for at most one context	`archsh:PresentationNameShape`	Violation
A `skosxl:prefLabel` is for no single context	`archsh:CanonicalNameForEveryContextShape`	Violation
An element has at most one name per context and language	`archsh:OneNamePerContextShape` (SPARQL)	Violation
Each name is also the element's plain `skos:altLabel`	`archsh:PresentationNameAlsoPlainShape` (SPARQL)	Warning
A label expression has exactly one `arch-vis:expression`, a string	`:LabelExpressionShape` (core-vis shapes)	Violation
A label expression is for at most one context	`:LabelExpressionShape`	Violation
`arch-vis:labelExpression` points to an `arch-vis:LabelExpression`	`:LabelExpressionUseShape`	Violation
A picture has at most one `schema:contentUrl` (an `xsd:anyURI`) and at most one context	`archsh:PictureShape`	Violation
An `arch:prefVisNotation` is for no single context	`archsh:CanonicalPictureShape`	Violation
A picture for a context has a `schema:contentUrl`; an element has at most one picture per context	`archsh:PictureForAudienceShape` (SPARQL)	Violation
A diagram element has at most one style for every context, and one for each	`:DiagElementShape` (core-vis shapes, SPARQL)	Violation
A style is for at most one context	`:StyleShape`	Violation

What a modelling tool does¶

Lets the reader pick a presentation context, or none, and labels with it: names, label expressions and — through its notation set — the look, switched together.
Evaluates the label expression that applies for each diagram element and draws its lines, again whenever the model changes.
Lets the modeller say a diagram element's own expression for the context shown, or for every context, and a name for an audience; renaming in place renames the canonical name.
Writes SKOS-XL names with their plain skos:altLabel, and the resources it creates with IRIs.
Lets the modeller give an element a picture for every audience and one per audience, and a diagram element its look — a picture inside it, or a picture as its figure — for the context shown or for every context; draws each diagram element with its style for the context shown laid over its style for every context.

Vocabulary¶

Term	In	What it is
`arch:inPresentationContext`	core 0.5.0	The presentation context a SKOS-XL name, a picture, a label expression or a style is for
`arch:prefVisNotation`, `arch:altVisNotation`	core	An element's picture for every audience, and its others — one per audience with a context
`schema:ImageObject`, `schema:contentUrl`	schema.org	A picture as a resource, and its address
`arch-vis:style`	core-vis 0.7	A diagram element's look: one for every context and one per context
`arch:usesNotationSet`	core	The notation set a presentation context is drawn with
`arch:presentationContextScheme`	core	A metamodel's scheme of presentation contexts
`arch-vis:LabelExpression`	core-vis 0.7	What a label says, as text with placeholders
`arch-vis:labelExpression`	core-vis 0.7	Gives a label expression: on a style, a notation or a presentation context
`arch-vis:expression`	core-vis 0.7	A label expression's text
`skosxl:Label`, `skosxl:literalForm`, `skosxl:altLabel`	SKOS-XL (W3C)	A name as a resource, its text, and an element's alternative name
`skos:prefLabel`, `skos:altLabel`	SKOS (W3C)	The canonical name, and the plain form of every other name