Structure your glossary, taxonomy, and metrics catalog

||Connect docs via MCP

Build the simplest structure that meets your requirement, sequence the rollout so the catalog actually gets populated, and treat the glossary as the context layer that grounds AI—not just a place to store definitions. This guide helps you decide between a single glossary and many, model metrics and KPIs correctly, and avoid the over-engineering that leaves a catalog empty. It's for the team designing and governing a business glossary, taxonomy, or metrics catalog.

When to use what

Atlan gives you several mechanisms. Match the simplest one to the requirement—don't stack redundant mechanisms on the same asset.

Mechanism	Use it for	Don't use it for
Glossary term	The semantic identity of a business concept or metric; the single source of truth for a definition; the node AI reasons over	Per-column technical descriptions (use the description field); access isolation
Category / subcategory	Organizing terms by domain or term-type within one glossary; governance-routing groups	Access control—it isn't enforced at this level
Glossary (top-level)	The access-control boundary; alignment to ownership and stewardship	A separate one per product line or use case (sprawl)
Tag / classification	A fast, filterable visual cue; cross-cutting compliance indicators	Domain ownership; per-value sensitivity granularity
Custom metadata	Structured, enumerated properties used for filtering, routing, reporting, or audit (use an options/picklist type for categoricals)	Anything whose value is unclear; synonyms intended for AI search
Domain	Ownership and organizational grouping; scoping AI search context	Storing something that's really just a tag

Access control is glossary-level only. Permissions are enforced at the top-level glossary, not at category or subcategory level. If two groups must be isolated, they need separate glossaries. Settle this trade-off before you build structure: category-level access control isn't available, so plan any required isolation as separate top-level glossaries from the start.

Domains vs data taxonomy—different constructs. Atlan domains are ownership and organization containers, and a shared asset can appear in multiple domains (a dimension table can belong to more than one). Your data taxonomy (the classification of data subject areas) is best represented with glossary categories. When you need two hierarchies—an organizational hierarchy and a data taxonomy—use domains for the former and glossary categories for the latter, and validate the fit with a small configuration experiment rather than assuming one answer.

Tagging granularity. Roll classification tags up to the regulatory category (for example PCI), not the specific value—this keeps them a scannable, cross-cutting cue rather than a per-value sensitivity model.

Owner vs steward. Put the hands-on operator: the person end users contact when data is wrong, who acts on tasks and maintains the asset—in the native Owner field. Capture the program-accountable owner in custom metadata. Assign ownership at the asset/table level, not per lineage hop or per column.

Metrics and KPIs are a stricter tier of term

A plain business term (Customer, Market Segment) needs a name, business-language description, classification, owner, and certification status. A metric or KPI isn't a separate product—it's the same construct with additional required fields:

1. Formula / calculation: in the dedicated formula field, never buried in the business-context description.
2. Data sources: the systems, tables, and columns each component is computed from.
3. Refresh frequency: how often it's recomputed.
4. Benchmarks / historical trend: what "good" looks like.
5. Owner: the business person accountable for the number.
6. Certification status: draft → verified → deprecated.

One term per distinct formula. If the calculation differs at all—even by unit (kg vs pieces) or audience (internal vs external): create separate, explicitly named terms, give them a shared alias for search, and relate them to each other. Collapsing different formulas into one term pollutes the AI context layer and breaks per-field lineage. A human can infer a variant from a tag; an AI agent needs the full formula on the asset it reasons about.

Link the metric to technical assets at the column level, not the report. Linking at the column level lets Atlan propagate the term to the related assets that consume that column, so downstream uses inherit it—confirm the current propagation behavior and direction in the product reference. Report-only linking denies AI the specificity to know which field carries the metric.

Where each metric property lives: placement drives searchability, so don't improvise it per term: human-facing priority content (definition, business context, caveats) goes in the README in tabular form; structured attributes (grain, unit of measure, sensitivity flag, effective date) go in custom metadata; SQL examples go in linked query assets, not embedded in the README; and synonyms go in the description or alias field, not in custom metadata (which search generally doesn't weight—confirm current search behavior in the product reference). Fields like certification status, alias, description, and linked terms tend to carry the most search and discovery weight—invest there first, and confirm the current search-ranking behavior in the Atlan product documentation before optimizing.

Designate one certified core glossary as the source of truth for critical metrics and CDEs—the verified, owned, governance-gated definitions that reporting and AI trust. Compare other glossaries' terms against it for alignment and deduplication, and expose only certified KPIs to business users via a read-only "certified metrics" persona.

Recommended sequence

Structure before content; content before linkage.

1. Build the skeleton first: the glossary → category → subcategory hierarchy, driven by domain ownership and governance routing (who approves changes determines the glossary split). Keep the total under roughly ten glossaries.
2. Populate terms next. Import terms only after the structure exists—importing into an empty platform yields templates with no dropdowns and forces rework. Enrich physical assets first (AI-assisted where available), then generate candidate terms, letting AI draft while humans review and certify.
3. Link terms to assets last, once connectors are live—full value materializes when terms attach to real physical assets, at the column level.
4. Populate first, govern later. Default to no approval workflow in phase 1: the goal is catalog hydration, and a required approval loop gates it and kills the demand signals you need. Introduce targeted workflows only once you have roughly 100+ terms and have identified the high-sensitivity term types worth gating. Frame it as "govern what matters, not everything."
5. The structure is easy to reorganize later: a top-level glossary can become a category under a larger domain—so don't let analysis paralysis block your first glossary. Start flat, named after your pilot domain, and revisit hierarchy after ownership is confirmed.

For same-term-different-meaning across business units or regions: create domain-specific instances of the term (one per domain), each with its local definition, and link them to each other: don't force one universal definition. Assign assets to domains before AI enrichment so descriptions come out domain-appropriate. For a conformed enterprise-plus-local model, create a canonical enterprise term and link business-unit variants to it with a standard relationship type.

Migrating from a legacy catalog: don't import every legacy entry as a term—many "terms" in a legacy catalog are really technical field descriptions, and importing them 1:1 pollutes the glossary. Run two parallel workstreams: push technical descriptions, synonyms, and reference links directly onto columns and tables as asset attributes (grouped under a clearly transitional, deletable custom-metadata set); and build genuine business terms from scratch, linking them to assets in a later phase. Push descriptions to the user description field by default (it tends to carry more search and discovery weight—confirm current search behavior in the product reference); reserve rich-text README content for supplementary material. Two mechanics that de-risk the load: design the structure in the platform first and export it as your import template (so the file matches what the importer expects, dropdowns included); and for large loads with deep hierarchy and asset links (several hundred terms and up), request a sample flattened export from the legacy tool before choosing between a spreadsheet load and a scripted SDK load—the sample decides which path is realistic.

Steward cold-start. Stewards stall without a scoped first action. Identify the 5–15 most-confused terms in one critical report, run one live example, and frame the ask as "half an hour a week," not a project. Hand stewards a template exported from Atlan itself, run AI enrichment alongside the human track so they review and certify drafts rather than write from scratch, and set a firm publish date. Convene the actual contributors (analysts, not directors) rather than holding broad "governance awareness" forums before any terms exist.

Review cadence by tier: critical metrics/KPIs quarterly; standard business terms annually; project-specific terms at milestones and closeout; deprecated terms archived (not deleted) after roughly six months of deprecation status. Run a lighter QA pass alongside: monthly (owners present, descriptions and links unbroken), quarterly (accuracy, usage, deprecation candidates), annually (structure). Calibrate change control to the change type—a typo needs no approval, a definition tweak needs the term owner, a formula or scope change needs the governance forum.

Common pitfalls

• Assuming category-level access control exists: it doesn't; isolation requires separate glossaries.
• Turning on approval workflows at kickoff: you get an empty catalog that never hydrates.
• Linking one term to many assets across different formulas or domains: breaks AI reasoning and per-field lineage.
• Importing legacy entries or column names 1:1 as terms: pollutes the glossary with technical noise.
• A separate glossary per product line or market: 30–40 glossaries, overlapping access, no ownership boundary, and forced copy-paste to signal adoption.
• Stacking term + tag + custom metadata all saying the same thing—maintenance overhead and signal confusion.
• Putting synonyms in a custom-metadata field and expecting AI search to use them—put them in the description as a keyword block, or in the alias field.
• Free-text custom metadata for categoricals: you can't filter on it, and the attribute type generally can't be changed after it's created (confirm current custom-metadata behavior in the product reference).
• Pitching the glossary as "definition storage" divorced from the AI workflow—for AI consumption, term-to-asset linkage matters far more than folder hierarchy.

Troubleshooting

• A missing connector or incomplete lineage is blocking rollout. Don't gate the whole rollout on one missing piece. Deliver the coverage you can now, handle the gap as a scheduled follow-on phase (manual or utility lineage for the missing flow), and frame it as phased delivery rather than a blocker.
• A user holds a role but can't act on terms. A role alone may not grant term access—check that the user is also attached to a persona that carries the relevant glossary permission (see Governance, access, and personas).
• A term won't move to a different category or glossary. Reproduce before dismissing it: try both drag-and-drop and the move-term action on a different (non-search-filtered) term. If drag-and-drop works, use it as the workaround and raise a support ticket.
• AI descriptions reference decommissioned sources. Find the inference path first—stale lineage edges, residual metadata in old SQL, or outdated enrichment input docs—then fix by root cause rather than re-running blindly.
• Backup or transient tables cluttering the catalog. Use crawler exclusion (a regex on the naming convention) so excluded assets autoarchive on the next crawl; don't delete manually.
• You suspect duplicate terms. Surface candidates before restructuring, align the target taxonomy (keep hierarchy shallow), and merge onto the certified core glossary. Route the mechanics of duplicate-detection reporting to the relevant report generator and product reference rather than hand-rolling it.
• Tag or term over-propagation along lineage. Out-of-box propagation can silently over-tag downstream derived fields. Switch propagation to name-based matching, exclude calculated/derived fields (see the propagation controls in the product reference), and always test on a sample lineage graph first.

For bulk-upload mechanics (template columns, file formats, category syntax), follow the current Atlan product documentation—those specifics change and aren't restated here.

Related

• Metadata enrichment: for AI-assisted term generation, description quality, and grounding the semantic layer.
• Governance, access, and personas: for glossary-level access boundaries and term-governance workflows.
• Product reference: bulk-upload template mechanics, connector coverage, and the current maturity of metrics/KPI lifecycle, term-relationship types, and AI glossary features.