Business Glossary: one definition per concept¶

The Business Glossary is Datahub's single, governed home for what your business words mean — one owner, one definition, and a link to the data that implements each concept.

This is where "what does active mean?" stops being a recurring Slack argument and becomes a published, owned definition the whole organisation can find.

Statuses4 · approval-gated

Relationship types5

ImportCSV · Excel · AI enrich

Consumed bySearch · HERC · DNA graph

When to choose this¶

Define a business concept once

Pick Customer — define it once, with the steward's name, the date approved, the related concepts, and the catalog assets that implement it.
Make terminology searchable

When someone joins, they type NRR into the platform and get the definition, the metric that calculates it, and the dashboard it appears on.
Govern naming and ownership

Terms transition draft → under review → published with reviewer approval, and every change is journaled.
Wire vocabulary to data

Customer (term) → customers (catalog asset) → Customer 360 (data product) → contract. The chain holds.

When not to reach for the Glossary

Technical column names → those live in the Catalog as column descriptions.
Process-step labels → those belong to the Process module.
Metric names → each metric has its own definition; link the term to the metric, don't duplicate it.

How a term connects to your data¶

A term is not a lonely dictionary entry — it is the hub that everything else hangs off. It links to catalog columns and documents through typed edges, relates to other terms, connects to metric definitions, can be wrapped as a data product to reach a contract, and is picked up by the DNA graph so search and HERC answer from the same source of truth.

flowchart LR
    TERM(["Business term<br/>name · definition · owner · status"])
    ASSET["Catalog columns / documents<br/>defines · measured by · sourced from · documented in"]
    REL["Related terms<br/>parent · child · related · synonym · see also"]
    METRIC["Metric definitions"]
    DP["Data product"]
    CON["Data contract"]
    DNA[("DNA graph<br/>term ↔ asset · term ↔ term")]
    HERC(["HERC<br/>define · who owns · what depends on"])
    SEARCH["Platform search"]
    TERM -->|typed asset link| ASSET
    TERM --> REL
    TERM -->|linked metrics| METRIC
    TERM -->|register as data product| DP
    DP -->|linked products| CON
    TERM -.->|graph edge| DNA
    ASSET -.->|graph edge| DNA
    DNA --> HERC
    TERM --> SEARCH
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class TERM accent

Figure 1 — A term is the hub. It links to catalog columns and documents through typed edges, relates to other terms, connects to metric definitions, and can be wrapped as a data product to reach a contract; the same edges feed the DNA graph, so search and HERC answer from one definition.

Why teams reach for this

Define a concept once and everything hangs off it — the catalog assets that implement it, the related terms, the metric that measures it, the contract that governs it. New joiners search a word and get the one answer; HERC and the DNA graph answer from the same definition, so nobody relitigates "what does active mean?"

Ask HERC "what's our definition of Customer?" and it looks up the term, returns the definition, and offers follow-ups — show linked assets, show related terms, who owns this? — using the term's tags and domain to steer related questions. Datahub's DNA graph picks up term ↔ asset and term ↔ term edges automatically, so "what depends on Customer?" routes through the graph and returns downstream entities across modules.

Concepts¶

Concept	What it is	Notes
Term	A business concept with a name, definition, examples, and metadata.	The atomic unit of the glossary.
Domain	A grouping (Finance, HR, Sales). Owners are by domain.	System table — admins manage.
Term relationship	A typed edge between two terms (parent / child / related / synonym / see also).	Drives the relationship browser and HERC's term-cluster answers.
Term-asset link	A typed edge from a term to a catalog column (defines, measured by, sourced from, derived from) or a document (documented in, policy source, referenced by, evidence for).	Stored as datamesh graph edges; the same edge surfaces on the asset's schema / Glossary tab.
Term-metric link	A link from a term to a metric definition.	Drives the term's Metrics tab and the metric's Linked Glossary Terms card.
Audit log	Every state change and edit, with who and when.	Plus journal in `/admin/audit-log`.

What the Glossary looks like¶

Surface	Where	What you see
Overview	`/glossary`	KPIs (terms total, by status, by domain), top contributors, the filterable terms list.
Term detail — Overview	`/glossary/terms/{id}`	Name, definition, examples, synonyms, abbreviations, owner, status with state-machine actions, domain, tags.
Term detail — Relationships	`/glossary/terms/{id}`	Other terms it relates to: parent, child, related, synonym, see also.
Term detail — Linked assets	`/glossary/terms/{id}`	Catalog columns and documents linked to this concept, each with its link type.
Term detail — Metrics	`/glossary/terms/{id}`	Metric definitions linked to this term.
Term detail — History	`/glossary/terms/{id}`	Audit log of every state change and edit.
Domains	`/glossary` (Domains tab)	The domain registry — Finance, HR, Sales, etc. Each domain owns its own terms.
Builder	`/glossary/terms/new`, `/glossary/terms/{id}/edit`	Full-page workspace with definition, examples, synonyms, abbreviations, related-term picker, tag picker, asset linker.

Setup — what an admin does once¶

Prereq	Where	Why
Domains	`/glossary` → Domains tab	Every term belongs to a domain. Eight are seeded (Finance, Sales, Marketing, Human Resources, Operations, IT & Technology, Customer, Legal & Compliance); tenants typically add a few.
Owner teams	`/admin/teams`	Each domain has an owner team.
Roles	`/rolegroups`	`glossary.terms.read`, `glossary.terms.write`, `glossary.terms.approve`; domain management is a separate module role (`domains.domains.manage`).
AI provider (optional)	`/admin/integrations` → AI Provider Keys	Required for AI-enriched bulk import.

Drafting a term¶

The simplest path:

Open /glossary → New term.
Name it. Net Revenue Retention. Add aliases (NRR) and optional abbreviations.
Define it. One sentence first; expand below. Add 1–2 examples.
Pick a domain and a steward team.
Relate it. Related to → Customer churn. Parent of → Gross Revenue Retention.
Link assets. If the metric nrr exists in the catalog, link to it. If a dashboard renders the term, link to it.
Submit for review. A task lands in the Glossary Approvers role group's inbox.
Approve. Once approved, the term is published and visible to everyone with read access.

How review routing works

Submit for review starts a governed approval and drops a task in the Glossary Approvers inbox in Tasks. When the term's domain has no steward and nobody on the fallback role may approve it, the submit window asks you to choose a reviewing group (never a single person) with someone other than you who holds glossary.terms.approve; the task goes to that group's team inbox. An approver publishes it — or rejects it back to draft. Every transition, and every field edit, is journaled to the term's History tab and to /admin/audit-log.

Editing a published term

Changing what the review approved (the name, summary, definition, abbreviation, synonyms, examples, notes or domain) sends a published term back to draft, out of the published glossary until an approver publishes it again. Changing only its Business Owner or Steward keeps it published.

Owner and steward

The Business Owner and the Steward must be people with an active Datahub account: not a locked or archived user, and not the built-in System User. The pickers offer only those people, and any other id (from an integration or an AI agent) is refused with a message that says why. Pick "-" to clear the owner, the steward or the domain; clearing a published term's domain sends it back to review, like any domain change.

Linking a term to a related term, an asset or a metric (and removing such a link) is a change to that term, so it follows the term's domain like editing it does: only members of the term's domain can, unless the term has no domain. The metric's own Linked Glossary Terms card meets the same rule.

A term under review is frozen

While a term is under review, its wording and domain cannot change, so the approver publishes exactly what was submitted. The term page locks those fields, and an import row or an AI agent's edit that would change them is refused with a message that says so. To change the wording, cancel the review (Cancel review on the term page) and submit the term again, or wait for the approver's decision. Its Business Owner and Steward can still change, because the review does not approve them.

Bulk import with AI enrichment¶

When you already have a glossary in a spreadsheet, use Import on /glossary (CSV or Excel, up to 10 MB). The AI enrichment step is what turns a 200-row spreadsheet into a usable glossary in an afternoon instead of a quarter.

flowchart LR
    UP["Upload<br/>CSV · Excel"]
    MAP["Map columns<br/>name · short description · definition · domain"]
    AI["AI enrichment · optional<br/>domain · short description · definition"]
    REVIEW{"Review<br/>each row"}
    DRAFT["Lands as draft"]
    DROP["Excluded"]
    SUBMIT["Submit for review<br/>in batches"]
    UP --> MAP --> AI --> REVIEW
    REVIEW -->|accept / edit| DRAFT
    REVIEW -->|skip| DROP
    DRAFT --> SUBMIT
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class AI accent

Figure 2 — Import pipeline. AI enrichment (optional) sits between column mapping and review, proposing a domain, short description, and definition for the fields you left blank; you accept, edit, or skip each row, and accepted rows land as drafts you submit in batches.

Upload CSV / Excel.
Map columns to fields (name, short description, definition, domain, …).
AI enrichment (optional) — the platform reads each row and, for the fields you left blank, proposes: a domain from your domain list, a short description, and a definition. It never overwrites values you already filled in, and it does not propose examples, related terms, or asset links.
Review row-by-row. Accept, edit, or skip each enrichment. The preview marks a row as an error, with the reason, when it changes a term in a domain your role group does not work in, files a term into one, or changes a term that is under review. The import follows the same domain rules as editing a term by hand.
Confirm. New terms land as a draft, and so does a published term the import changes. A published term the import leaves unchanged stays published, and an empty cell leaves that field as it is. Refused rows are skipped and the rest of the file still imports. Each term's History names you as the one who made the change. You then submit the drafts for review in batches.

Why the AI step matters

Enrichment drafts the definition, suggests a domain, and writes a short description for the rows you left blank, so a steward only has to review, not author. It is the difference between a glossary you finish this week and one that stalls for a quarter.

The governance lifecycle¶

Every term moves through a governed state machine: an author drafts, a reviewer approves, and only then is the definition published as the source of truth. Retired terms are marked deprecated — still findable, flagged as superseded. Archiving is a separate soft-delete that hides a term from default lists; it is not one of the four workflow statuses.

stateDiagram-v2
    direction LR
    state "Under review" as UnderReview
    [*] --> Draft: Create
    Draft --> UnderReview: Submit for review
    UnderReview --> Published: Approve
    UnderReview --> Draft: Reject
    Published --> Draft: Content edit
    Published --> Deprecated: Deprecate
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class Published accent

Figure 3 — The governed lifecycle across the four statuses (draft, under review, published, deprecated). A reviewer must approve before a term is published — the source of truth — rejections return it to draft, and changing a published term's content or domain returns it to draft for re-approval (an owner or steward change does not). Deprecated is the terminal retirement state; archiving is a separate soft-delete. Every transition is journaled.

Status	Meaning	Who can move it
Draft	Author is iterating. Changing a published term's content or domain returns it here; an owner or steward change does not.	Author or anyone with `glossary.terms.write`.
Under review	Submitted for approval. Task lands in `/tasks`. Its wording and domain are frozen until the review is decided or cancelled; its owner and steward can still change.	Triggered by Submit for review (`glossary.terms.write`).
Published	Source of truth.	Approver action via the workflow (`glossary.terms.approve`).
Deprecated	Still findable, marked as superseded. Terminal — a deprecated term is not re-opened.	Direct transition (`glossary.terms.approve`).

Draft, under review, published, and deprecated are the four workflow statuses. Archiving is separate: a soft-delete (is_archived) available from any status with glossary.terms.write, hiding the term from default lists (system terms cannot be archived). The review/approval routing — who approves, in how many steps — is configurable per workflow definition (/admin/workflows); the status vocabulary itself is fixed in code.

Linking a term to a contract¶

Terms link to contracts the same way every other entity does — via Data Products:

Open the term → Register as Data Product in Part of N data products.
Wrap the term (alone, or alongside the asset / metric that implements it).
Contract → Linked Products → link the product.

See Data Products.

Limitations¶

Limit	Why	Workaround
One canonical definition per term.	The glossary is the one place — if it has three definitions, it's not a glossary.	Use the synonyms and abbreviation fields, or a synonym / see also relationship to another term, for variant phrasing. Use the definition itself for nuance.
Term-asset links are typed but not weighted.	We don't model "primary" vs. "secondary" implementation.	Use the description field on the link to add context.
Bulk import is per-row commit (not transactional across the file).	If one row fails validation, the others still land.	The preview shows row-level errors; fix and re-upload only the failed rows.
A term's domain is changed on the term page only.	The domain is part of what a review approves and decides who reviews, so a move follows the review rules: a published term goes back to review, and a term under review cannot move.	The Data Mesh Explorer does not file a term under a domain or remove it from one; it says where to go instead. Open the term, Edit, and pick its domain there.
AI enrichment uses the active provider key — costs come out of your provider quota.	We don't bury usage.	Disable enrichment if you want to import without AI.
Status transitions are governed; you can't bypass review.	Defeats the point of a governed glossary.	Build a fast-track workflow definition with a single approver if your org needs faster turnover.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who defined this term?"	Detail → History tab.
"Who approved the publish?"	Detail → History tab → the published transition row.
"Who owns Customer?"	Detail → Owner team.
"Show every term touched by a specific user."	`/admin/audit-log` filtered by `glossary` + actor.
"Has the definition changed since the audit cut-off?"	Detail → History tab — every edit timestamp.

Troubleshooting¶

Symptom	Likely cause	Fix
"Term name already exists" on create	Same name in same domain.	Pick a different domain, or add a qualifier (Customer (B2B)).
Submit for Review is greyed	Missing required field (definition / domain / steward) or you lack `glossary.terms.write`.	Complete fields; check role.
Linked asset shows not found	The asset was archived.	Update the link or restore the asset.
AI enrichment never finishes	Provider key missing or rate-limited.	`/admin/integrations` → AI Provider Keys; reduce batch size.
Approver doesn't see the task	They're not in the Glossary Approvers role group.	Add them in `/rolegroups`.
"…this glossary term is under review…" when saving or importing	The term was submitted, so its wording and domain are frozen until the review ends.	Cancel the review on the term page (Cancel review) and submit it again, or wait for the decision.
Search misses an obvious term	Term is in draft status — drafts are excluded from default search.	Filter by all statuses or publish the term.

Arriving from a domain's detail page narrows this list to that domain automatically — a banner names it, with a one-click way back out. See Domains.