Glossary document

A glossary holds one concept scheme, the vocabulary of one bounded context.

Identity

boundedContext is the sole key of a glossary. The file is named <boundedContext>.glossary.yaml.

The path carries no meaning. A glossary file can sit in one folder with the other glossaries, next to the code of its bounded context, or in a slice directory. It can sit inside the repository or outside it.

The invariant ABoundedContextNamesOneGlossary holds boundedContext unique across the glossaries that one atlas lists.

Document shape

A glossary 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 spells the same fields in snake_case, one to one: prefLabels is pref_labels, boundedContext is bounded_context, rejectedOn is rejected_on.

The specification field Concept.scheme is never written in a document. The document is the scheme that the field points at.

A JSON-LD context maps the fields to SKOS. The fields with no SKOS property map to project local properties under the specification namespace.

Fields of a glossary

Field	Type	SKOS	Rule
boundedContext	String	none	The name the model gives the bounded context. Sole key of the document
titles	Set of Label	none	One title per language the glossary carries
concepts	Set of Concept	none	The concepts of this scheme and of no other

Fields of a concept

Field	Type	SKOS	Rule
id	String	part of the concept IRI	kebab-case. Unique among the concepts of this scheme
prefLabels	Set of Label	skos:prefLabel	At most one entry per language. No other concept of the scheme carries the same language and text
altLabels	Set of Label	skos:altLabel	Further current names of the same concept
hiddenLabels	Set of HiddenLabel	skos:hiddenLabel	Words that were dropped. Each entry carries a reason and a date
definitions	Set of Label	skos:definition	At least minimumDefinitionsPerConcept entries. The default value is 1
scopeNote	String, optional	skos:scopeNote	Where the term holds and where it does not
example	String, optional	skos:example	One case from the practice the term comes from
historyNote	String, optional	skos:historyNote	Who decided what, and when. The words of the deciding party are allowed verbatim
status	ConceptStatus	none	How far the term is settled
origin	ConceptOrigin	none	Who put the word into circulation
standardRef	String, optional	none	The name of the standard. Not null where origin is standard
kind	ConceptKind	none	What the term names in the model
grounding	Set of String	none	The places that use the term, as a path with an anchor or as a reference to a board event
broader	concept id, optional	skos:broader	Names a concept of the same scheme
related	Set of concept id	skos:related	Every member names a concept of the same scheme

Optional fields

The optional fields of a concept are scopeNote, example, historyNote, standardRef and broader.

An optional field accepts three inputs: absence from the document, the value null, and a value of the declared type. A value of any other type is a departure.

Value types

Label

One name of one thing in one language.

Field	Type	Content
language	Language	The language of the name
text	String	The name itself

Two labels with the same language and the same text are one label.

HiddenLabel

A word that was considered and dropped.

Field	Type	Content
language	Language	The language of the dropped word
text	String	The dropped word itself
reason	String	The ground on which it was dropped. Length of at least one character
rejectedOn	Timestamp	The day on which it was dropped

Two hidden labels are one hidden label where all four fields agree.

Enumerations

Language

The languages a glossary carries. Whether this is a closed list the specification extends, or an open BCP 47 tag space, is an open question in the specification.

Value	Meaning
de	German
en	English

ConceptStatus

Value	Meaning
confirmed	The deciding party settled the term
unconfirmed	The term is in use, and nobody settled it
proposed	The term is proposed and not yet in use
deprecated	The term was replaced. It stands for readers of the old version

ConceptOrigin

Value	Meaning
owner	A word of the project that keeps the glossary
standard	A word a standard coined first. standardRef names that standard
llm	A word a language model coined. Probabilistic generation produces terms without a decision

ConceptKind

Value	Meaning
entity	A thing with an identity in the domain model
event	Something that happened in the domain
field	A field of an entity or of an event
role	A party that acts in the domain, human or automated
actor	A system that reacts on its own
value	A value type, or one single value of an enumeration
rule	A domain rule the domain experts name

MappingRelation

The relation of a term of one scheme to a term of another. The atlas holds the field that takes these values.

Value	Meaning
exact_match	The same thing, interchangeable in every context
close_match	Near enough to stand for the term in the translation chain
broad_match	The term on the other side is wider
narrow_match	The term on the other side is narrower
related_match	Related, and neither term contains the other

Example

boundedContext: billing
titles:
  - {language: de, text: Abrechnung}
  - {language: en, text: Billing}
concepts:
  - id: invoice
    prefLabels: [{language: de, text: Rechnung}, {language: en, text: Invoice}]
    altLabels: []
    hiddenLabels: []
    definitions: [{language: de, text: Die Zahlungsaufforderung an den Kunden nach Lieferung.}]
    scopeNote: null
    example: null
    historyNote: null
    status: confirmed
    origin: owner
    standardRef: null
    kind: entity
    grounding: [code:Invoice]
    broader: null
    related: [mehrwertsteuer]
  - id: mehrwertsteuer
    prefLabels: [{language: de, text: Mehrwertsteuer}]
    hiddenLabels:
      - language: en
        text: VAT
        reason: British VAT follows a different law. The translation hides that.
        rejectedOn: '2026-09-08'
    definitions: [{language: de, text: Die Steuer nach deutschem Umsatzsteuergesetz, die auf der Rechnung ausgewiesen wird.}]
    scopeNote: Bleibt in Code und Dokumenten unübersetzt.
    status: confirmed
    origin: standard
    standardRef: UStG
    kind: value
    grounding: [code:Mehrwertsteuer]
    broader: umsatzsteuer
    related: []