Building Glossaries

A glossary is where your organization writes down what its information means, and connects those meanings to the datasets, APIs and fields that hold it. In its simplest form it is a flat list of terms — a vocabulary. Terms can also be organized hierarchically, forming a taxonomy, and set in relation to each other to build out complete ontologies.

You never have to decide up front which of those you are building. The GUI adapts as the glossary grows in complexity, exposing the functionality relevant to what you actually have, so a glossary can start as a handful of definitions and become an information model without being redesigned.

This page covers one way of designing a glossary that starts from the data you already have, how to build one in Katalogue and a brief section with theory behind the concepts vocabulary, taxonomy and ontology.

Designing a Glossary

This section describes one way to design a glossary in Katalogue — an approach we have seen deliver value in practice. It is not the only way and it is not a prescription. Every organization works differently, and choosing a methodology is yours to do; treat what follows as a worked example to borrow from and adapt.

The approach in a sentence: start from the data you already have, and add meaning where it matters. It is deliberately the reverse of modelling the business first and connecting the model to reality afterwards — which, in our experience, tends to stall before it delivers anything, because it asks for agreement about everything before anything is useful.

Start With Reality, Not a Blank Model

Sync your datasources before you write a single definition. Once the datasets and fields are in Katalogue they are already useful: people can find what exists, see where it lives and who owns it. That is value on day one, with no modelling required.

The glossary then grows out of what you found. A field whose meaning is disputed, a column name nobody can decipher, two systems that clearly hold the same thing under different names — each is a concrete reason to define something, and each definition earns its place by answering a question somebody actually asked.

Working this way also gives you a feedback loop, which modelling on a blank page does not. A definition written up front can stay wrong for years, because nothing compares it to reality. A definition attached to real fields is compared the moment anyone looks at them: it either matches what the column holds or it does not.

Add Meaning Where It Matters

You do not need to describe everything. Most fields are self-explanatory or unimportant, and describing them anyway is how a glossary becomes a maintenance burden nobody keeps up with.

Spend the effort where meaning is contested, reused or expensive to get wrong: the terms two departments define differently, the figures that end up in a report to the board, the concepts every new employee has to be taught. If a definition would settle a recurring argument, write it. If nobody would ever look it up, leave it.

Give the first pass a finish line, though. “Where it matters” on its own is reactive — you learn that a definition was needed when somebody complains, and nothing ever tells you the work is done. Pick something small and bounded that you can complete: the fields behind one report, one system’s customer master, the terms one team argues about most. Narrow scope, finished properly, is worth more than broad coverage left half-done, and a completed piece is what convinces everyone else this is worth doing.

Layer Your Glossaries

A term does not mean the same thing everywhere, and one glossary cannot hold every meaning without becoming vague. Where one meaning genuinely serves everyone, one glossary is enough. Where it does not, use several, layered.

This is often a good starting point for a large organization in which competing definitions already exist, whether or not anybody has written them down. Getting them recorded side by side, where they can be seen and compared, makes them far easier to reason about — and regularly reveals that two of them were the same thing all along, or that the disagreement was about something narrower than it appeared.

The layers:

an enterprise glossary with the terms the whole organization shares — few, agreed and stable;
domain glossaries — Sales, Finance, Logistics — where a domain adds the detail it needs on top of those shared terms;
system glossaries describing the information model of one system, in that system’s own vocabulary.

Record which layer a glossary belongs to in its type, so the layering is visible in Katalogue rather than implied by how the glossaries happen to be named. The type is free text, so those three are a starting point rather than a fixed list — an external glossary, holding definitions your organization did not write, such as an industry standard or a regulator’s terminology, is a common fourth.

That list describes the finished structure, not the order you build it in. You will usually start with the glossary closest to the data you have just discovered — a system or a domain — and the enterprise glossary will be the last to fill up, as terms prove to be genuinely shared.

Customer is the usual example. The enterprise glossary defines what the organization means by a customer. The Sales glossary refines it for its own purposes. The CRM’s glossary describes what a customer record is in that system, which may include prospects who are not customers at all in the business sense. All three are legitimate, and conflating them is what makes glossaries untrustworthy.

Names only have to be unique within a glossary, so each layer can use the word that is right for it. What turns those layers into a connected model, rather than the same word repeated three times, is linking them. Type @ in a description or definition and pick the asset from the list that appears: Katalogue records the reference and the backlink, so each definition can be read together with the ones it relates to.

Link the competing definitions to the one they vary from, and say how they differ. The CRM glossary’s Customer might be defined as “an organization we hold a commercial relationship with — the same as @Customer in the enterprise glossary, but B2B only; private individuals are held as Contact”. A reader who lands on either one can now see the other, and the difference is stated rather than left to be discovered.

Bottom-Up Has to Meet Top-Down

Growing a glossary from the data has one weakness worth naming: it has no built-in abstraction step. Discovery produces definitions where the data is — in a system, in a domain — and nothing lifts them into a shared vocabulary on its own. Left alone, an organization ends up with several well-maintained system glossaries and an empty enterprise glossary, which is the fragmentation it set out to fix.

So the bottom-up work eventually has to meet a deliberate top-down effort: someone looking across the glossaries, deciding which terms the organization genuinely shares, and driving those to agreement. That effort is much cheaper once the local glossaries exist, because the candidates are already written down and connected to real data — the argument is about which definition to share, not about what exists.

The signal to promote a term is finding the same thing defined compatibly in two glossaries. When that happens:

define it once in the shared glossary above them, in language neither domain owns;
link the local definitions to it, stating how each varies;
give the shared term an owner with authority across the domains that use it — a term nobody can decide for is a term that stays in Draft forever.

Name Things the Way the Business Says Them

Use the words people actually say, not the ones the source systems use. Prefer the singular — Customer, not Customers — and avoid abbreviations that only one team understands.

Keep the description to what the thing is, and aim for something a colleague outside the owning team can read once and understand. An Attribute has a definition as well, which is the other half of the question: how a Measure is calculated, or how a Dimension’s values are determined. Where the data is stored and which system is authoritative belong in neither — they are the fields you associate with it. If two teams cannot agree on a single meaning, that is usually two concepts sharing a name, and separating them into different glossary layers is the fix.

Give Everything a Real Owner

Katalogue requires an owner on every asset, so the question is never whether one is set — it is whether it means anything. Assigning everything to a placeholder user, or to whoever is senior enough not to object, answers nothing. What you want is someone who can be asked “is this still true?” and who would notice if it were not.

Ownership matters more than completeness. A small glossary with real owners stays true; a large one without them decays quietly.

Add Complexity When It Is Needed

A glossary does not have to arrive fully formed, and nothing here has to be decided in advance — Katalogue is built so that a glossary can grow without being redesigned. The same rule applies to every kind of complexity on offer: add it when something actually asks for it.

Structure. Begin flat. Add a hierarchy when you catch yourself grouping — Vehicle above Car and Truck — and add relationships between entities when a hierarchy can no longer express what you mean, such as an Employee who works on a Project in a Department. This is the progression from vocabulary to taxonomy to ontology described above, and adding depth to a glossary in use is far easier than designing it up front.

Workflow. Statuses stay out of the way until you define more than one for the glossary side of Katalogue, and leaving them alone is a perfectly good default. A large organization with a mature installation may eventually want a Draft → Review → Approved workflow, so that a domain expert can work in the open without the rest of the organization mistaking unfinished definitions for agreed ones — see Asset Statuses.

Scope. One glossary is enough until competing definitions start making it vague. That is the point where layering earns what it costs to maintain, and splitting a glossary that has grown too broad is ordinary work rather than a rebuild.

Define Once, Use Everywhere

The point of associating an attribute with the fields that carry it is that the definition stops being an opinion in a document. Those fields inherit the description, so one agreed definition reaches every column that holds that information, in every datasource — and it reaches the applications, developer tools and AI that read Katalogue through its API.

That connection is also the best test of the model. An attribute you cannot find a single field for is worth questioning. A field everyone depends on that no attribute describes is a gap worth filling.

Layering glossaries does not contradict this. Each layer defines its own term once, for its own scope, and a shared term is defined once and referenced from the layers below rather than copied into them. What you never want is the same definition written out twice: then there are two things to maintain and no way to tell which one is authoritative.

Creating a Glossary

What a Glossary Holds

A glossary holds two kinds of asset, and you choose between them with a single role when you add one:

Role	Is a	What it is for
Entity (also called a Term)	Entity	Something your information model describes, such as Customer or Order. Can be nested, and attributes can be placed under it to describe it further.
Dimension	Attribute	An axis of analysis: a property of an entity that you describe, filter or group by — such as Customer Name or Country. Can be associated with the fields that carry it, and given a list of permitted values.
Measure	Attribute	A property of an entity that you quantify and aggregate — such as Order Amount or Quantity. Can be associated with the fields that carry it, and given a unit.

Entities are where the model describes your business. Attributes are where the model meets your physical data: associate an attribute with the fields that carry it, and those fields take on its description. This means one description, maintained in one place, serves every column in every datasource that holds that information.

The full hierarchy of a glossary is therefore:

Glossary
Entities, optionally nested under each other
Attributes, either directly in the glossary or under an entity
Attribute Values, under a Dimension

Adding Assets

Glossaries are created from the Glossaries page, reachable from the Glossaries option in the navigation pane. A glossary needs a name, and optionally a type, a description, an owner and a status.

The type says which kind of glossary this is — Enterprise Glossary, Domain Glossary, System Glossary or External Glossary, as described under Layer Your Glossaries. The Katalogue glossary that ships with Katalogue is typed System Glossary, since it describes one system: Katalogue itself. The type is free text, so you can use whatever your organization calls its layers, but keeping to a small agreed set is what makes it useful: every list of glossaries can be filtered and sorted by it, and a glossary’s type is part of its search context, so customer : enterprise narrows a glossary search to the enterprise-wide ones.

Open the glossary to add assets to it. Its Assets tab holds the whole tree — entities, the attributes under them, and the values under a Dimension — and the buttons above the tree act on whatever you have selected:

+ Add with nothing selected adds a new asset to the glossary.
+ Add with a row selected copies that asset, which is a quick way to add several similar ones.
Add Child adds an asset under the selected row: an asset under an entity, or an attribute value under a Dimension. Unlike a copy, the child starts empty with only its parent pre-filled. On a Measure the button is disabled, since only a Dimension can have values.
Edit and Delete act on the selected assets, and support editing several at once.

Adding an asset always opens the same form. Pick a role at the top, and the form shows the fields that role needs — an entity type for an Entity, or a definition, sensitivity and field associations for a Dimension or Measure, plus a unit for a Measure. Name, description, parent, owner and status are shared by all three.

Changing the Role of an Asset

The role is not fixed. Editing an asset and choosing a different role converts it, keeping its description, parent, owner, status, custom properties, references and history. What cannot survive the move is discarded, and the form says so under the role picker before you save:

Changing a Dimension to a Measure discards its attribute values, because only a Dimension can have them.
Changing a Measure to a Dimension discards its unit, because only a Measure has one.
Changing a Dimension or a Measure to an Entity discards its definition, because only an attribute has one.
Changing an attribute to an Entity discards both its attribute values and its associations to fields, because an entity has neither.

An entity that has children cannot become an attribute — only entities can have children, so move or delete the children first.

Attribute Values

A Dimension can be given a list of attribute values: the permitted contents of the fields it describes. Customer Country might have the values SE, NO and DK. Each one has a name, an optional code for programmatic use, an optional description and a status.

Values can be added and edited wherever the attribute appears: from the Values tab on the attribute itself, or by opening the attribute in a glossary’s Assets tab, on an entity’s own page, or in All Attributes — select a Dimension and use Add Child. A value shown in one of those trees is a row like any other: tick it and the Edit and Delete buttons act on it.

A value inherits its attribute’s glossary, owner and data sensitivity rather than carrying its own, so those columns are left empty on its row — the attribute one line above states them.

A Measure is quantified rather than enumerated, so it carries a unit instead and has no values. The Values tab is disabled for it.

Browsing Attributes Across Glossaries

An attribute belongs to exactly one glossary, but it is sometimes useful to see every attribute in Katalogue at once — for example to find one to associate a field with or find duplicate names between glossaries. The Glossaries page has an All Attributes tab for that, listing attributes from all glossaries with the glossary each belongs to. Attributes there open to their values in the same way, and the filter searches the values too — including the value code. Tick or untick it in the filter’s column selector like any other column.

Entity Types

Entity types are labels that classify the entities within a glossary. The default type is Term, but admins can define additional types such as Chapter, Section and Information Area. They work best alongside hierarchies, giving the entities at one level a name for what that level is.

Admin users manage them under the glossary’s Entity Types tab. Once defined, they appear as a dropdown when adding or editing an entity.

Entity types are defined per glossary and has a name, an optional code for programmatic use and an optional description. One type per glossary can be set as the default to have that pre-selected for new entities. Entities with no selected type fall back to a generic “Term”.

Deleting

Deleting an asset deletes what it owns. The confirmation dialog always lists what is about to happen before anything is removed:

Deleting an attribute deletes its attribute values, and the fields it described lose that description. The fields themselves are never deleted.
Deleting an entity that has children lets you choose: tick Also delete all child assets to remove them with it, or leave it unticked to lift the children up one level and keep them.
Deleting a glossary deletes its entities, attributes, attribute values and entity types, and every field described by one of those attributes loses that description.

Vocabulary, Taxonomy, and Ontology

Vocabulary, taxonomy, and ontology represent increasing levels of structure and semantic complexity in knowledge organization. A vocabulary defines a list of terms, a taxonomy imposes a hierarchical (parent/child) structure on those terms, and an ontology enables complex, relational modeling of domains with inference rules. They are often used together to structure, classify, and understand data.

Key Differences and Components

Vocabulary: A list of preferred terms to ensure consistent usage in a domain.
Taxonomy: A classification system organized hierarchically (a tree structure), such as “Product -> Vehicle -> Car”. It uses “broader” or “narrower” relationships.
Ontology: A complex knowledge model that defines classes, subclasses, properties, and relationships between entities. It supports logic, inference, and complex, non-hierarchical links (a graph structure).

Comparison Table

Feature	Vocabulary	Taxonomy	Ontology
Structure	Flat list	Hierarchy (Tree)	Network (Graph)
Relationship	None/Weak	Parent-Child (Is-a)	Complex/Arbitrary
Purpose	Definition	Categorization	Reasoning/Inference
Complexity	Low	Medium	High

Usage Scenario Examples

Vocabulary: Creating a standard, consistent set of technical terms for a document.
Taxonomy: Organizing website navigation or an e-commerce product catalog.
Ontology: Modeling complex relationships, such as how “Employee” relates to “Project,” “Skills,” and “Department” in a database to infer knowledge.