Skip to content

IRI Minting — How Linked.Archi Tools Name Model Resources

A model resource keeps its IRI for life. Other models, commits, reviews and links point at it, and a three-way merge matches it by name. This page is the layout every tool mints: la-gram, la-gram-git, every converter and the ArchiMate derivation rules. Why the layout is what it is, and what was rejected, is DD-41.

{base}{notation}/{modelId}/                    the model namespace ({ns})
{ns}model                                      the arch:Model
{ns}{kind}/{id}                                a resource with an identity of its own
{view}#{node|link}/{id}                        a shape drawn in a view
{owner}/{part}[/{key}]                         a part of another resource
{ns}graph/model|semantic|views|provenance      the DD-15 graphs

The model namespace

{ns} is {base}{notation}/{modelId}/, where:

  • base is the publisher's base IRI. It is https://example.org/ unless one is configured.
  • notation is the notation's slug; DD-29 lists the reserved segments. Two tools write model there instead: the ArchiMate converter, whose --path-model defaults to it, and la-gram, for a model with no notation. The converter keeps its default so that the IRIs it has written keep their form; --path-model archimate gives the slug.
  • modelId is a UUID for a model made in a modeller, or the converter's stable model identifier.

No tool reads the segment. The model states its namespace on itself, every tool writes both statements, and a resource's model is found by this namespace or by arch:inModel:

@prefix arch: <https://meta.linked.archi/core#> .
@prefix vann: <http://purl.org/vocab/vann/> .
@prefix m:    <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/> .

m:model a arch:Model ;
    vann:preferredNamespacePrefix "m" ;
    vann:preferredNamespaceUri "https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/" .

The namespace is an https: or http: IRI that ends in / and holds no # or ?:

  • a shape adds the one # an IRI may hold, so a namespace with a # would give it two;
  • a URN has no path for a name relative to @base to resolve against, or for a page to be served from.

la-gram refuses any other namespace for a new model, and the converters a base IRI that would give one. The conformance check reports a model saved with one. In a model saved with a # in its namespace, la-gram mints a new shape flat, {ns}node-{uuid}, as it did before this layout.

Resources with an identity of their own: {ns}{kind}/{id}

The kind is one path segment, and the id follows it. The id is one segment too, unless the source identifies the resource by several parts: a Backstage entity is {kind}/{namespace}/{name}, three segments that parse back because no part of an entity reference can hold a /.

kind Names
element an element (arch:Element and its subclasses)
relationship a qualified relationship, asserted or derived
view a view or diagram
folder a folder
decision an architecture decision record
documentation a documentation section

A new kind is added to this table before any tool mints it. The kind is generic: it is element/…, never ApplicationComponent/…, so a retype keeps the IRI.

Shapes in a view: {view}#{kind}/{id}

A node or a link is drawn in one view and never moves to another: Duplicate view and paste make new shapes. It is named in that view: the view's IRI as it was minted, #, the kind and an identifier unique within the view.

kind Names
node a diagram node: arch-vis:ArchNode, ContainerNode, and a LabelNode that stands on its own, such as a note
link a diagram link: arch-vis:Link
  • {view} is the IRI of the view the shape's arch-vis:view names, whatever its form: {ns}view/{id}, or, for a BPMN collaboration diagram whose view no index names, the process that is its view, {ns}element/{processId}.
  • A shape inside a container is named in the view too, {view}#node/{id}. Containment is said by arch-vis:inNode, not by the name.
  • A shape's parts stay in its fragment, joined with /: {view}#link/{id}/point/0. An IRI holds at most one #.
  • Two shapes of one view never share an IRI. A converter fails a conversion in which they would.

A shape's IRI pasted in a browser opens its view's page and scrolls to the shape: the browser fetches {view} and keeps the fragment (Static publishing).

Choosing the identifier

Take the first of these that applies:

  1. Made in a modeller: a random UUIDv4, chosen when the resource is created and never changed.
  2. The source's own identifier, where the source format keeps it unique within the model, or for a shape within its view.
  3. A digest of the key that identifies the resource: the first 20 hex characters of its SHA-256. The converters build the key with PartIri.encode(…) and digest it with IriSegment.digest; the derivation rules and la-gram join IRIs with spaces (Derived relationships). The same key always gives the same digest, in every run.

A shape that the source gives no identifier of its own takes the identifier of what it shows, its element or its relationship, since a view draws each once.

Source Element, relationship, view Node, in its view Link, in its view
la-gram UUID UUID UUID
la-gram, importing an Exchange file source id source id (n.id) source id (c.id)
ArchiMate Exchange, Archi source id source id (n.id) source id (c.id)
BPMN source id; a view is the index's view id, else a collaboration diagram's process, else the diagram's id BPMNShape id BPMNEdge id
Structurizr, PlantUML source id the element's id the relationship's id
LeanIX fact sheet id the fact sheet's id —
Backstage entity reference, lowercased; no views — —

The form is fixed per source format, and does not change with the other files of a run. Where a format keeps its identifiers unique only within a file, as BPMN does, a view's shapes all come from one file: several BPMN files form one model only through a diagram index, which gives each file's view an id and refuses one id twice, and a model without an index is one file. Their shape ids are therefore unique in the view. An element or relationship keeps its id: the same id in two files of one model names one resource, and a conversion whose files describe it differently fails.

A relationship that the source gives no identifier is named after what identifies it, and bounded: PlantUML composes its ends and its label, Backstage its type and its two entity references. A Structurizr documentation section is named by its owner and its file, {ns}documentation/{ownerId}/{file}, and only one without a file by its position under its owner. A BPMN element with no id is a part of the element it sits in (below); one with nothing to sit in gets a digest of the file and its place in it. A BPMN view is the one the index names, {ns}view/{viewId}. Where no index names one, a collaboration diagram's view is the first process of its participants that the file defines, so its IRI is the process's, {ns}element/{processId}: the one view that is not {ns}view/{id}. Any other diagram's view, a process diagram's included, is {ns}view/{diagramId}. Two collaboration diagrams of one file whose first process is the same are then one view; their shapes stay apart, since one file's shape ids are unique. la-gram names an imported Exchange file as the ArchiMate converter does, so an import and a conversion of the same file give the same local names.

Rules for the identifier:

  • An id holds no /, except between the parts of a compound source identity, and no #. A source identifier that is not a plain path segment, such as a Structurizr view key with a space, is percent-encoded.
  • An identifier longer than the segment budget is bounded with IriSegment.bounded.
  • The source identifier of an element, relationship or view is written as skos:notation, so a digest can be traced back to the source.

Parts of another resource: {owner}/{part}[/{key}]

A part has no life outside its owner, so it is named under it (PartIri in the converters). The owner of a shape's parts is the shape, so they stay in its fragment.

Part IRI Keyed by
route cell, the rdf:List of arch-vis:points {link}/points/{i} its position, from 0
route point, arch-vis:Point {link}/point/{i} its position, from 0
style, arch-vis:Style {node or link}/style nothing: the placement's style for every presentation context
style for one presentation context {node or link}/style/{context} the presentation context
the label of a node or a line, the arch-vis:LabelNode its arch-vis:label names: a BPMN BPMNLabel, a line's text moved in la-gram {node}/label, {link}/label nothing: one per node or line
an anonymous composite, a source element with no id of its own, such as a BPMN messageEventDefinition {owner}/{localName}, then {owner}/{localName}_2 and so on nothing for the first of its kind under its owner; after it, the order the source lists them
label expression, arch-vis:LabelExpression {node}/label-expression, {node}/label-expression/{context} the presentation context, where it is for one
a concept's name for a presentation context {concept}/name/{context}, then /{language} when it is not in English the presentation context and the language
a concept's picture {concept}/picture, {concept}/picture/{context} the presentation context, where it is for one
folder entry, schema:ListItem {folder}/item/{digest} the member it lists
property pair, schema:PropertyValue {owner}/property/{digest} what it says
derivation activity, the prov:Activity that generated a derived relationship {relationship}/activity nothing: one per derivation
the activity's association, the prov:Association that names the rule as its plan {relationship}/activity/association nothing: one per activity
any other part {owner}/{kind}/{digest} its key in the source, else what it says

So a route point of link l1 in view v1 is {ns}view/v1#link/l1/point/0, and its node's style {ns}view/v1#node/n1/style.

Positions are used only where the position is the identity: a list's cells and points, and anonymous composites of one kind, which nothing else tells apart. Everything else is keyed by content, so inserting one value does not renumber the others. A {context} key is la-gram's shortHash of the presentation context's IRI, 8 hex characters of FNV-1a, not the 20-character SHA-256 digest above; only la-gram mints those parts, so the two never have to match. Parts are joined with /, never with -.

Derived relationships

The ArchiMate derivation rules mint relationships no modeller drew, and la-gram mints one for each relationship a file states only as a triple. None of them has an identifier from a source or a modeller, so each is named after what identifies it, with the digest above, of a key that joins a rule's name and IRIs with single spaces:

Resource IRI Key
a qualified relationship for a triple the model states without one: the rules' QualifyRelationships, and la-gram when it opens a model {ns}relationship/{digest} the triple's subject, predicate and object
a derivation: the qualified relationship, of the relationship's class, that a rule derives {ns}relationship/{digest} the rule's name, then the subject, predicate and object of each of its two premises
its derivation activity, the rule applied to the premises {relationship}/activity nothing: one per derivation
the activity's association, which names the rule as its plan {relationship}/activity/association nothing: one per activity

The rules and la-gram build the key alike, so a triple in a file opened in la-gram and run through the rules gets one resource. It is not PartIri.encode's key, which prefixes each part with its length: SPARQL's STRLEN counts characters, where Kotlin and JavaScript count UTF-16 code units, so the two would differ for an IRI outside the Basic Multilingual Plane. No IRI holds a space, so IRIs joined by spaces are unambiguous. With no model loaded, or several, the rules mint in urn:linked-archi: instead of a model's namespace.

In the NordFreight example, whose namespace is https://meta.linked.archi/examples/nordfreight/, DR3 derives that the Azure cloud serves the tracking service: the cloud realizes the tracking portal, which DR2 derived, and the portal serves the service. The key is

DR3 https://meta.linked.archi/examples/nordfreight/AzureCloud https://meta.linked.archi/archimate4/onto#realizes https://meta.linked.archi/examples/nordfreight/TrackingPortal https://meta.linked.archi/examples/nordfreight/TrackingPortal https://meta.linked.archi/archimate4/onto#serves https://meta.linked.archi/examples/nordfreight/TrackingService

and the derivation, its activity and the association are

https://meta.linked.archi/examples/nordfreight/relationship/d163205cd09e3dbf9875
https://meta.linked.archi/examples/nordfreight/relationship/d163205cd09e3dbf9875/activity
https://meta.linked.archi/examples/nordfreight/relationship/d163205cd09e3dbf9875/activity/association

Valid and Potential in the ArchiMate 4.0 modelling guide shows them in Turtle, with their premises.

Reading IRIs

  • Read meaning from the triples: the type from rdf:type, the view from arch-vis:view, the element from arch-vis:archElement, the model from arch:inModel. Elements, relationships and views state arch:inModel; shapes and parts do not, and their model is the one whose namespace they are in.
  • An IRI is read for two things only:
    • the model namespace a resource is in, by matching the model's vann:preferredNamespaceUri;
    • the resource a shape or a part belongs to: the nearest enclosing resource, which is the longest prefix of the IRI, cut at a / or at the #, that is itself a resource of the model. For {view}#link/{id}/points/0 that is the link, {view}#link/{id}; for the link, it is the view; for a part of a Backstage entity, it is the entity, all three segments.
  • Names minted before DD-41 are read as they were.
    • la-gram's: {ns}{kind}-{id} is a resource or a shape, and {owner}-style, {owner}-style-{context}, {link}-points-{i}, {link}-p{i}, {link}-label, {node}-label-expression, {concept}-name-{context} and {concept}-picture are parts of their owner.
    • The converters': {ns}view/{v}/node/{id}, {ns}view/{v}/link/{id} and {ns}view/{v}/connection/{id} are shapes, and their parts are under them with /.
    • The derivation rules': {ns}derivation-{sha1} is a derivation, {ns}derivation-activity-{sha1} its activity and {ns}derivation-activity-{sha1}-association the activity's association; {ns}relationship-{sha1} is a relationship the rules or la-gram qualified. The rules derive and qualify nothing that is there under such a name.
  • A display label falls back to the last segment of the path or the fragment only when there is no skos:prefLabel or rdfs:label.
  • A tool never rewrites the local part of an IRI, whichever tool minted it, so names minted before DD-41 keep their names. A namespace change swaps only the namespace (below).

Turtle

A prefixed name cannot hold a / or a # unescaped, so a tool that writes Turtle binds a prefix per kind and a prefix per view, and encodes each IRI in the model namespace in this order:

  1. a prefix per kind, where the rest is a plain local name: me:{id};
  2. a prefix per view, for a shape and its parts, with each / of the fragment escaped as \/: mv3ef7da72:node\/{id}, mv3ef7da72:link\/{id}\/point\/0;
  3. an IRI relative to @base: <element/component/default/payments-service>;
  4. the full IRI.
Prefix Namespace
m: {ns}
me: {ns}element/
mr: {ns}relationship/
mv: {ns}view/
mf: {ns}folder/
md: {ns}decision/
mdoc: {ns}documentation/
mg: {ns}graph/
mv{hash}: {view}#, one for every view the file draws shapes in
@base {ns}

m is the model's vann:preferredNamespacePrefix: a model whose prefix is shop gets shope:, shopr:, shopv{hash}: and so on. {hash} is the first 8 hex characters of the SHA-256 of the view's IRI, so a view's prefix does not change when other views are added or removed. Where two views of one file give one prefix, the view whose IRI sorts first keeps it and the other's shapes are written relative to @base. A derived prefix that a vocabulary in the file already binds to another namespace is not bound: the vocabulary keeps it, and those IRIs are written relative to @base. The prefixes are bound for the model a file is about, and the IRIs of any other model in the file are written in full.

N3.js cannot write this as it is. Given a baseIRI, it makes an IRI relative before it looks for a prefix, so an element comes out as <element/…>, never me:…, and it leaves an IRI in full when a later segment is shorter than three characters, as in …/points/0. A writer that encodes in the order above does it.

What the view prefixes save depends on how long the view ids are:

Measured on Written as above la-gram's flat names Shapes relative to @base
a rebuild of ArchiSurance's ArchiMate views as la-gram saves a model, view ids UUIDs (938 nodes, 386 links, 1,647 parts of them; 17,578 triples) about 1,034 KB 997 KB 1,188 KB
la-gram's import of the ArchiSurance 3.1 Exchange file, view ids the source's (id-54880; 27,407 triples) 1,163 KB 1,145 KB 1,176 KB
the same, gzipped 91 KB 111 KB 90 KB

Gzipped, the layout is smaller than the flat names, since a view's shapes sort together. On the converted ArchiSurance graph, whose view ids are short, the shapes cost 2%. The other formats write every IRI in full, so the layout changes their size by a fraction of a per cent.

Static publishing

A generator that writes one page per resource writes it at the resource's IRI, relative to the base: element/{id}/index.html, relationship/{id}/index.html, view/{id}/index.html. A Backstage element's three segments are three directories. Served at the base IRI, the site opens any of these IRIs pasted in a browser.

  • Elements, relationships and views get pages. Shapes and parts do not.
  • A shape is a fragment of its view's page. The page gives every shape its fragment as id: id="node/{id}", id="link/{id}", id="link/{id}/point/0". A browser given {view}#node/{id} loads the view's page and scrolls to the node, and a :target style can highlight it. The diagram has to be in the page, as inline SVG or as a list with anchors: the inside of an SVG loaded with <img> cannot be a target.
  • A link to a shape is its view's page and the fragment: view/{v}/index.html#node/{id}, never a page of its own. A server that redirects view/{v} to view/{v}/ keeps the fragment, since a browser carries it across a redirect that sets none.
  • A part of an element, relationship or view, such as a name for a presentation context, is shown on its owner's page.

Changing a model's namespace

Changing the namespace renames every resource in the model. Merged with a parallel change, that reads as "everything was deleted on one side".

  • Change it on the main branch, in a commit of its own.
  • The change swaps the namespace and keeps every local part as it is, names minted before DD-41 included, and the shapes move with their views.
  • la-gram asks before it changes the namespace of a model that is linked to Git, and keeps the model linked to its file, so that the next commit is the move.
  • A merge recognizes a namespace change between base and one side by the model's new IRI, {ns}model in the namespace its vann:preferredNamespaceUri states, and applies the old-to-new mapping to base and the other side before merging. la-gram-git merge does so whichever side moved; la-gram, into a model moved in it. A namespace stated without moving the IRIs changes only where new IRIs are minted, and merges as a value.
  • A converted model gets a new namespace by being converted again with a new base. A namespace changed in la-gram would differ from the next conversion's.

Examples

Made in la-gram: two elements in a view, a style on one node, and a line with one bend:

@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 rdf:      <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix skos:     <http://www.w3.org/2004/02/skos/core#> .
@prefix xsd:      <http://www.w3.org/2001/XMLSchema#> .
@prefix m:  <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/> .
@prefix me: <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/element/> .
@prefix mv: <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/view/> .
@prefix mv3ef7da72: <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/view/4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40#> .
@base <https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/> .

m:model a arch:Model .

me:6ad3ed74-f0b2-41aa-9e0c-adafbf5320d4 a am4:ApplicationComponent ;
    skos:prefLabel "Billing"@en ;
    arch:inModel m:model .

me:0d8f2c64-7b1e-4a93-b5d0-3e9c1a7f6b28 a am4:ApplicationComponent ;
    skos:prefLabel "Payments"@en ;
    arch:inModel m:model .

mv:4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40 a arch:View , arch:Diagram ;
    skos:prefLabel "Billing overview"@en ;
    arch:inModel m:model .

mv3ef7da72:node\/e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b a arch-vis:ArchNode ;
    arch-vis:view mv:4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40 ;
    arch-vis:archElement me:6ad3ed74-f0b2-41aa-9e0c-adafbf5320d4 ;
    arch-vis:style mv3ef7da72:node\/e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b\/style .

mv3ef7da72:node\/e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b\/style a arch-vis:Style ;
    arch-vis:fillColor "#ffe8cc" .

mv3ef7da72:node\/5a7c9e1b-3d2f-4b8a-a6c4-8e0f2b4d6a19 a arch-vis:ArchNode ;
    arch-vis:view mv:4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40 ;
    arch-vis:archElement me:0d8f2c64-7b1e-4a93-b5d0-3e9c1a7f6b28 .

mv3ef7da72:link\/9c3e5a71-2b4d-4f60-9a8b-7c6d5e4f3a21 a arch-vis:Link ;
    arch-vis:view mv:4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40 ;
    arch-vis:source mv3ef7da72:node\/5a7c9e1b-3d2f-4b8a-a6c4-8e0f2b4d6a19 ;
    arch-vis:target mv3ef7da72:node\/e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b ;
    arch-vis:points mv3ef7da72:link\/9c3e5a71-2b4d-4f60-9a8b-7c6d5e4f3a21\/points\/0 .

mv3ef7da72:link\/9c3e5a71-2b4d-4f60-9a8b-7c6d5e4f3a21\/points\/0
    rdf:first mv3ef7da72:link\/9c3e5a71-2b4d-4f60-9a8b-7c6d5e4f3a21\/point\/0 ;
    rdf:rest rdf:nil .

mv3ef7da72:link\/9c3e5a71-2b4d-4f60-9a8b-7c6d5e4f3a21\/point\/0 a arch-vis:Point ;
    arch-vis:point-x "230"^^xsd:double ;
    arch-vis:point-y "227"^^xsd:double .

The node's full IRI is https://example.org/archimate/2d441909-2be6-4dfe-aaa5-c7ee59edbc4c/view/4b7e0c12-9d3a-4f61-8e2b-1c5d7a9e3f40#node/e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b. The prefixed names are what a writer that encodes as Turtle describes produces. N3.js on its own writes the elements as <element/…> and every shape in full.

A model la-gram made before DD-41 keeps its names, such as m:element-6ad3ed74-…, m:node-e1f2a3b4-… and m:link-9c3e5a71-…-points-0. A resource or shape added to it later gets the layout above.

From an ArchiMate Exchange file, converted or imported into la-gram, the source's own ids are used: element me:id-1a2b3c, and in view id-v77 the node {ns}view/id-v77#node/id-n42 and the link {ns}view/id-v77#link/id-c9.

From a BPMN collaboration diagram whose view no index names, a shape is named in the process that is its view, as ArchiSurance's message flow {ns}element/Process_issue-new-policy#link/Message_Policy_di. A process diagram's shapes are named in {ns}view/{diagramId}.

From Structurizr, element 5 drawn in two views gets one node in each, named after the element:

@prefix arch:     <https://meta.linked.archi/core#> .
@prefix arch-vis: <https://meta.linked.archi/core-vis#> .
@prefix me: <https://example.org/c4/bigbank/element/> .
@prefix mv: <https://example.org/c4/bigbank/view/> .
@prefix mv00494f1d: <https://example.org/c4/bigbank/view/SystemContext#> .
@prefix mve7282c35: <https://example.org/c4/bigbank/view/Containers#> .

mv:SystemContext a arch:View , arch:Diagram .
mv:Containers a arch:View , arch:Diagram .

mv00494f1d:node\/5 a arch-vis:ArchNode ;
    arch-vis:view mv:SystemContext ;
    arch-vis:archElement me:5 .

mve7282c35:node\/5 a arch-vis:ArchNode ;
    arch-vis:view mv:Containers ;
    arch-vis:archElement me:5 .

That is https://example.org/c4/bigbank/view/SystemContext#node/5 and https://example.org/c4/bigbank/view/Containers#node/5.

Conformance check

la-gram-git check, or a SHACL shape, reports:

  • a resource in {ns} whose local part is not model, graph/…, {kind}/{id} with a kind from the table, or a shape or part under one of these;
  • a shape whose IRI is not {view}#node/{id} or {view}#link/{id} for the view its arch-vis:view names;
  • an IRI with more than one #;
  • a part whose IRI is not under its owner;
  • a name minted before DD-41, {ns}{kind}-{id}, a part such as {owner}-style, a converter's {ns}view/{v}/node/{id}, or the derivation rules' {ns}derivation-{sha1}, reported as legacy, not as an error;
  • an identifier holding a character a path segment cannot, such as a space;
  • a model without vann:preferredNamespaceUri;
  • a model namespace that is not an https: or http: IRI ending in /, or that holds a # or a ?.