Skip to content

Authoring Cross-Language Mappings

A cross-language mapping document states that one modelling language's concepts correspond to another's: that TOGAF's Principle is broadly the same idea as ArchiMate's Principle, that a BPMN UserTask and an ArchiMate BusinessProcess are related but not equivalent. It is what lets a query written against one notation reach models written in another.

These documents are arch:crossLanguageMappings targets — a separate owl:Ontology per language pair set, registered on a metamodel manifest and loaded alongside the data. Three exist today: togaf-crossmappings.ttl, uaf-crossmappings.ttl and time-crossmappings.ttl. This page is how to write the next one.

Two levels, two mechanisms

The word "mapping" covers two jobs that use different predicates and live in different places. Getting them confused is the most common mistake here.

Type level Instance level
Relates bpmn:UserTask ↔ am:BusinessProcess — two classes <…/element/Task_1> ↔ <…/CRM-42> — two nodes
True of every model written in those languages exactly one pair of resources
Predicates skos:closeMatch, skos:relatedMatch, skos:broadMatch, skos:narrowMatch, and skos:exactMatch where scopes genuinely coincide skos:exactMatch by default; owl:sameAs for the documented exception
Authored in a *-crossmappings.ttl, once per language pair the reconciliation graph, {base}graph/reconciliation, per link
Governed by this page DD-11

This page is about the type level. For relating two specific nodes that describe the same real-world system, see DD-11 and the reconciliation method in Bridging Architecture Silos.

Neither level is ever produced by a converter. Mappings are editorial judgements about what two vocabularies mean, and no tool reading a model file is in a position to make them.

When you need one

Write a mapping document when a language or framework module is otherwise an island: its classes share arch:core supertypes with everything else, so ?x a arch:Element finds them, but nothing says which specific concept in another language a given class corresponds to.

You do not need one when:

  • The two sides already share a class. If your extension subclasses am:ApplicationComponent, subsumption already relates them. A mapping would add nothing.
  • You control both representations and can use one IRI. Cheapest answer available.
  • The correspondence is between individuals, not classes. That is instance reconciliation.
  • You want a reasoner to treat the classes as interchangeable. That is owl:equivalentClass, and it is deliberately not what these documents use — see below.

Choosing the predicate

All five SKOS mapping properties are available. Pick by how far the two concepts' scopes actually overlap, not by how convenient the mapping would be:

Predicate Use when Frequency in practice
skos:exactMatch the two concepts coincide in scope — interchangeable wherever either appears rare across languages; common between a full ontology and its own lite subset
skos:closeMatch the concepts are the same idea, with edges that do not quite line up the working default
skos:relatedMatch genuinely related, but different in kind or granularity the common case across frameworks whose abstractions differ
skos:broadMatch your concept is narrower than the target where one language subdivides what another lumps together
skos:narrowMatch your concept is broader than the target the inverse of the above

The guidance in arch:crossLanguageMappings is to prefer closeMatch over exactMatch unless the concepts genuinely coincide, and to expect relatedMatch to be the common case. The existing documents bear this out: time-crossmappings.ttl uses only closeMatch and relatedMatch, and uaf-crossmappings.ttl opens with uaf:Capability skos:relatedMatch am:Capability — because a UAF capability carries operational and strategic baggage an ArchiMate capability does not.

Not owl:equivalentClass, and not rdfs:subClassOf

owl:equivalentClass tells a reasoner the two classes have identical extensions, so every instance of one is an instance of the other, forever. That pulls OWL entailment into the everyday query path for what is an editorial judgement, and it is wrong on the facts for nearly every cross-language pairing.

rdfs:subClassOf is worse: it asserts a taxonomic relationship between two independently maintained vocabularies, so a change to either silently changes what the other entails. Use it within a language, never across one.

Both are also irrevocable in practice — once downstream consumers rely on the entailment, withdrawing the axiom breaks their queries. A SKOS mapping can be revised.

Consistent with the minimal-OWL profile in Architecture & Approach: OWL carries meaning, identity and classification; correspondence is description, and stays inference-free.

If you find yourself wanting exactMatch on most rows, that is usually a signal that the two "languages" are one language at two levels of detail. That case is real — BPMN Lite maps to full BPMN with skos:exactMatch throughout — but it belongs in the subset ontology itself, not in a separate mapping document.

The file

Follow the shape the three existing documents share.

@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix prov:    <http://www.w3.org/ns/prov#> .
@prefix cc:      <http://creativecommons.org/ns#> .
@prefix vann:    <http://purl.org/vocab/vann/> .

@prefix arch:    <https://meta.linked.archi/core#> .
@prefix mylang:  <https://meta.linked.archi/mylang/onto#> .
@prefix am:      <https://meta.linked.archi/archimate3/onto#> .
@prefix am4:     <https://meta.linked.archi/archimate4/onto#> .

<https://meta.linked.archi/mylang/crossmappings#>
    a                owl:Ontology ;
    owl:imports      <https://meta.linked.archi/mylang/onto#> ;
    cc:license       "http://creativecommons.org/licenses/by/4.0/" ;
    vann:preferredNamespaceUri    "https://meta.linked.archi/mylang/crossmappings#" ;
    vann:preferredNamespacePrefix "mylangxm" ;
    dcterms:creator  "Author Name"^^xsd:string ;
    dcterms:title    "Linked.Archi MyLang Cross-Language Mappings"@en ;
    dcterms:description '''Cross-language SKOS mappings between MyLang concepts and
other modeling languages in the Linked.Archi knowledge graph.

State here which mappings are official and which are editorial, and say so
per target language if they differ.'''@en ;
    dcterms:issued   "2026-09-05"^^xsd:date ;
    dcterms:modified "2026-09-05"^^xsd:date ;
    owl:versionInfo  "0.1.0"@en ;
.


#################################################################
# MyLang ↔ ArchiMate 3.2
#################################################################
#
# Editorial mappings — no official cross-framework specification
# exists. These express semantic proximity based on concept
# definitions in the two specifications.

## Core entities
mylang:Thing        skos:closeMatch    am:ApplicationComponent .

## Supporting concepts
mylang:OtherThing   skos:relatedMatch  am:Capability .

Points that are conventions rather than accidents:

  • owl:imports names only your own ontology, not the targets. Importing every target would drag four unrelated vocabularies into anything that loads the mappings. Targets are referenced by prefix; a consumer loads the ones they actually have.
  • No default @prefix :. The document declares no terms of its own, only assertions between other people's terms. The repository's registration check compares a default prefix against vann:preferredNamespaceUri where both are present, and these files sidestep that by having no default prefix at all.
  • One banner comment block per target language, with a note on whether the mappings in it are official or editorial. Where different targets have different provenance, say so per block rather than once at the top.
  • Bare triples, grouped by ## subsection. No blank nodes, no reification. A mapping document is meant to be readable end to end and diffable in review.
  • Assertions run from your concepts to theirs. All three existing documents put the local vocabulary in the subject position throughout. SKOS mapping properties are symmetric by definition, but symmetry is an entailment — a reasoner-free query has to look in the direction the triple was written, so consistency here saves every downstream query a UNION.

Registering it

A mapping document nothing points at will not be found. Add one line to the metamodel manifest:

    ## Cross-language mappings — MyLang ↔ ArchiMate 3.2, MyLang ↔ ArchiMate 4.0
    ## File: mylang-crossmappings.ttl
    arch:crossLanguageMappings    <https://meta.linked.archi/mylang/crossmappings#> ;

arch:crossLanguageMappings has rdfs:domain arch:Metamodel and rdfs:range owl:Ontology, so the subject is the manifest resource, not the ontology that defines your concepts. The two-line comment naming the file is the convention in every existing manifest — the manifest lists namespaces, and the comment is what tells a human which file to open.

This registration is what makes the mapping discoverable: a tool walking the manifest finds the document without being told it exists.

Naming and versioning

Convention Example
File name {lang}-crossmappings.ttl, beside the metamodel togaf-crossmappings.ttl
Namespace https://meta.linked.archi/{lang}/crossmappings# …/togaf/crossmappings#
Prefix {lang}xm togafxm, uafxm, timexm
Version owl:versionInfo, semver, starting 0.1.0 "0.2.0"@en

Version the mapping document independently of the ontology it maps from — they change for different reasons. Adding a target language or a batch of new rows is a minor bump. Changing an existing row's predicate is a breaking change, because a query filtering on skos:closeMatch silently stops matching a row that became relatedMatch. Bump accordingly and say what moved.

Keep dcterms:modified current. It is the only signal a consumer has that a mapping was revisited.

Recording where a mapping came from

This is the part most worth being careful about, because a reader cannot tell an official mapping from a considered guess by looking at the triples.

Where an official mapping exists, cite it and say so. togaf-crossmappings.ttl does this properly: its description names the ArchiMate specification appendix that defines the TOGAF ↔ ArchiMate mapping, and it carries both dcterms:source and prov:wasDerivedFrom pointing at the published document.

    dcterms:source      <https://pubs.opengroup.org/architecture/archimate3-doc/ch-Mapping-TOGAF-Content-Metamodel.html> ;
    prov:wasDerivedFrom <https://pubs.opengroup.org/architecture/archimate3-doc/ch-Mapping-TOGAF-Content-Metamodel.html> ;

Where none exists, say that, in the description and in the per-language banner comment. time-crossmappings.ttl is the model here: "These are editorial correspondences — no official mapping exists between the Gartner TIME model and ArchiMate, Backstage, or TOGAF."

A document may be mixed. uaf-crossmappings.ttl derives its UAF ↔ DoDAF rows from the OMG UAF specification's traceability appendix while its UAF ↔ ArchiMate rows are editorial, and it states both in the same description. That is the right level of honesty: the rows look identical in Turtle, so only the prose distinguishes them.

Querying across a mapping

The mapping document is not imported by anything — verified across the repository, no owl:imports targets a crossmappings namespace — so loading it is a deliberate act. That is intentional: a consumer who does not want editorial correspondences in their graph simply does not load the file, and nothing they already have changes.

Once loaded, a query crosses the mapping explicitly:

PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX am:   <https://meta.linked.archi/archimate3/onto#>

# Elements typed am:BusinessProcess, plus elements whose notation type a mapping
# document says corresponds to it.
SELECT ?element ?type WHERE {
    ?element a ?type .
    {
        FILTER(?type = am:BusinessProcess)
    } UNION {
        VALUES ?mapping { skos:exactMatch skos:closeMatch skos:relatedMatch }
        { ?type ?mapping am:BusinessProcess } UNION { am:BusinessProcess ?mapping ?type }
    }
}

Two things that trip people up. The anchor type has to be unioned in — a mapping relates am:BusinessProcess to other things and says nothing about itself. And the inner UNION covers both directions, because SKOS symmetry is an entailment that no reasoner is running here.

Narrow the VALUES list to the strength you actually accept. A governance report that treats a relatedMatch as equivalent will overstate its coverage.

Review checklist

  • Every row's predicate reflects real scope overlap, not convenience. Default to closeMatch; reach for relatedMatch where the abstractions differ in kind.
  • No owl:equivalentClass, no rdfs:subClassOf, no owl:sameAs between classes.
  • skos:exactMatch used only where the two concepts genuinely coincide in scope.
  • Every target class IRI exists in the ontology it claims to come from. A typo produces a triple about a class nothing defines, and nothing complains.
  • Official versus editorial stated, in the description and per banner block.
  • dcterms:source and prov:wasDerivedFrom present where a published mapping was followed.
  • owl:imports names your own ontology only.
  • Namespace, prefix and file name follow the table above.
  • arch:crossLanguageMappings line added to the metamodel manifest, with the file-name comment.
  • owl:versionInfo and dcterms:modified updated. Predicate changes to existing rows called out as breaking.
  • Local vocabulary consistently in the subject position.

Validating

Syntax-check the new file and the manifest you edited:

.scripts/validate.sh --syntax modelingLanguages/mylang/mylang-crossmappings.ttl
.scripts/validate.sh --syntax modelingLanguages/mylang/mylang-metamodel.ttl

.scripts/validate.sh --registration checks the asset index against the sources; mapping documents are not currently listed there, and an unlisted namespace is not an error. --ci runs the full sequence.

No SHACL shape validates the content of a mapping document — that a predicate is the right one for a given pair is a judgement, and there is nothing to check it against. Which is why the review checklist above is the actual control.