Atlas document

An atlas lists the glossaries of one domain and holds the links between their terms.

Identity

One atlas covers one domain. The domain is to the atlas what the bounded context is to the glossary.

The file is named atlas.yaml, or <domain>.atlas.yaml where several domains share a folder.

The atlas file marks the search root.

Document shape

An atlas is one YAML document. The fields stand at the top level. There is no envelope.

Field names are camelCase. Enum values are snake_case.

The specification field Mapping.atlas is never written in a document. The document is the atlas that the field points at.

Fields of an atlas

Field	Type	Rule
domain	String	The name of the domain the atlas covers. Counterpart of boundedContext
titles	Set of Label	One title per language the atlas carries
glossaries	Set of String	One URI reference per glossary of the domain
links	Set of Mapping	The cross context links. The field name is a working name and is not decided

Resolution of a glossary reference

Each entry of glossaries is a URI reference.

A relative reference names a local file. A tool resolves it against the directory that holds the atlas file.

An absolute https IRI names an external glossary. A tool fetches it as any other SKOS document.

There is no git specific scheme. A glossary in another repository has two forms of reference: a relative reference to a local checkout, or an https IRI to a published copy.

Fields of a link

Field	Type	Rule
from	concept reference	The term the link reads from
to	concept reference	The term in the other scheme that the link points at
relation	MappingRelation	One of the five values below
note	String, optional	How the translation chain carries the term

from and to each take one of two forms: <boundedContext>:<id>, or a full IRI.

note accepts absence from the document, the value null, and a string.

The invariant AMappingJoinsTwoDifferentSchemes holds the scheme of from different from the scheme of to.

Relation values

Value	SKOS
exact_match	skos:exactMatch
close_match	skos:closeMatch
broad_match	skos:broadMatch
narrow_match	skos:narrowMatch
related_match	skos:relatedMatch

Search rules

A tool walks up from the working directory until it finds an atlas file, or until it reaches the home directory of the user, or until it reaches the root of the filesystem.

The nearest atlas wins.

Two atlas files in one directory is an error. Neither file is nearer than the other, and the tool must not choose.

A single glossary validates without an atlas. Resolution of the links requires one.

Example

domain: shop
titles:
  - {language: en, text: Shop}
glossaries:
  - ./sales/sales.glossary.yaml
  - ./billing/billing.glossary.yaml
  - https://www.example.org/language/payments.glossary.yaml
links:
  - from: sales:customer
    to: billing:account
    relation: close_match
    note: Dieselbe Person, in Sales als Kunde geführt, in Billing als Konto.