Business Glossary & Taxonomy
Relevant source files
The following files were used as context for generating this wiki page:
- datahub-web-react/src/app/glossaryV2/BusinessGlossaryPage.tsx
- docs-website/src/learn/business-glossary.md
- metadata-ingestion/src/datahub/ingestion/source/metadata/business_glossary.py
- metadata-ingestion/src/datahub/ingestion/source/rdf/README.md
- smoke-test/test_resources/analytics_backfill/generate_glossary_terms.py
- metadata-service/restli-api/src/main/snapshot/com.linkedin.entity.aspects.snapshot.json
Introduction
The Business Glossary in DataHub serves as a centralized dictionary for standardized business terminology across an organization. Its primary purpose is to ensure consistency, regulatory compliance, and efficient data discovery by providing unified definitions for key concepts used in data collection, processing, and analysis. By standardizing terms, organizations reduce confusion caused by inconsistent naming conventions (e.g., "Customer Lifetime Value" having different meanings across Marketing, Sales, and Finance teams) and facilitate smoother onboarding for new employees.
The taxonomy is structured hierarchically, utilizing Glossary Terms for specific concepts and Glossary Nodes (often referred to as Term Groups) for logical organization. This system supports rich metadata including definitions, ownership, related terms, and institutional memory links. It integrates deeply with the rest of the metadata ecosystem, allowing assets like datasets, columns, and dashboards to be tagged with glossary terms to aid in Data Discovery and governance.
Sources: docs-website/src/learn/business-glossary.md:14-25, docs-website/src/learn/business-glossary.md:47-60, metadata-ingestion/src/datahub/ingestion/source/rdf/README.md:3-9
Core Data Model
The glossary is built upon two primary entities: GlossaryTerm and GlossaryNode. These entities utilize specific aspects to store their metadata and relationship information.
Glossary Entities & Aspects
| Entity / Aspect | Description | Key Fields |
|---|---|---|
| GlossaryTerm | Represents a single business concept. | name, definition, termSource, sourceUrl |
| GlossaryNode | A container or folder used to group related terms or other nodes. | name, definition, parentNode |
| GlossaryTermInfo | Contains the core properties of a term. | name, definition, parentNode, customProperties |
| GlossaryNodeInfo | Contains the core properties of a node. | name, definition, parentNode |
| GlossaryTerms | An aspect applied to other entities (e.g., Datasets) to associate them with glossary terms. | terms (List of associations), auditStamp |
| GlossaryRelatedTerms | Defines relationships between different glossary terms. | isRelatedTerms, hasRelatedTerms, values |
Sources: metadata-service/restli-api/src/main/snapshot/com.linkedin.entity.aspects.snapshot.json:694-818, metadata-ingestion/src/datahub/ingestion/source/metadata/business_glossary.py:46-77
Relationship Hierarchy
Glossary nodes and terms form a tree structure. A term or node can have an optional parentNode which points to a GlossaryNodeUrn, allowing for multi-level nested taxonomies.
The diagram shows the hierarchical relationship where Glossary Nodes act as folders containing either sub-nodes or terminal Glossary Terms.
Sources: metadata-ingestion/src/datahub/ingestion/source/metadata/business_glossary.py:270-305, metadata-ingestion/src/datahub/ingestion/source/rdf/README.md:40-47
Ingestion Framework
DataHub provides multiple methods to ingest business glossaries, ranging from manual UI creation to automated ingestion from YAML and RDF sources.
YAML Ingestion
The BusinessGlossaryFileSource allows users to define a glossary in a YAML file. The ingestion process materializes URNs for each term and node, mapping their hierarchy into the DataHub metadata model.
class BusinessGlossarySourceConfig(ConfigModel):
file: Union[str, pathlib.Path] = Field(
description="File path or URL to business glossary file to ingest."
)
enable_auto_id: bool = Field(
description="Generate guid urns instead of a plaintext path urn.",
default=False,
)
Sources: metadata-ingestion/src/datahub/ingestion/source/metadata/business_glossary.py:88-96
RDF/SKOS Ingestion
For organizations using standard ontologies, the RDF source supports SKOS (Simple Knowledge Organization System).
skos:Conceptis mapped toGlossaryTerm.skos:prefLabelis used for the term name.skos:definitionis used for the term definition.skos:broaderandskos:narrowerare mapped to term relationships.
Sources: metadata-ingestion/src/datahub/ingestion/source/rdf/README.md:31-50
Ingestion Flow Logic
The flowchart illustrates the transformation process from external raw glossary formats into Metadata Change Proposals (MCPs) acceptable by the DataHub Generalized Metadata Service.
Sources: metadata-ingestion/src/datahub/ingestion/source/rdf/README.md:73-82, metadata-ingestion/src/datahub/ingestion/source/metadata/business_glossary.py:440-454
User Interface & Management
The DataHub web application provides a dedicated "Business Glossary" page for exploring and managing the taxonomy.
Glossary UI Components
- BusinessGlossaryPage: The main entry point that fetches root terms and nodes using GraphQL queries (
useGetRootGlossaryTermsQueryanduseGetRootGlossaryNodesQuery). - GlossaryContentProvider: Manages the display and state of the glossary tree.
- CreateGlossaryEntityModal: Provides the interface for users with
manageGlossariesprivileges to create new terms or nodes directly from the UI.
Sources: datahub-web-react/src/app/glossaryV2/BusinessGlossaryPage.tsx:43-70, datahub-web-react/src/app/glossaryV2/BusinessGlossaryPage.tsx:96-115
Governance & Workflow
Standardizing a glossary often requires human oversight. DataHub Cloud introduces Approval Flows to manage changes to the glossary. This ensures that new terms or modifications to existing ones are reviewed by stakeholders before being finalized.
Sources: docs-website/src/learn/business-glossary.md:142-150
Programmatic Management
Developers can manage glossary terms using the DataHub Python SDK. The make_term_urn utility is used to generate identifiers, and MetadataChangeProposalWrapper is used to emit changes to the server.
Example: Creating and Attaching a Term
def create_glossary_term(term_name: str, definition: str, category: str):
term_id = term_name.lower().replace(" ", "_")
term_urn = make_term_urn(term_id)
term_info = GlossaryTermInfoClass(
definition=definition,
name=term_name,
termSource="INTERNAL"
)
return MetadataChangeProposalWrapper(entityUrn=term_urn, aspect=term_info)
Sources: smoke-test/test_resources/analytics_backfill/generate_glossary_terms.py:76-96
Summary
The Business Glossary & Taxonomy module in DataHub provides a robust framework for defining and organizing business metadata. By combining hierarchical nodes with detailed terms, DataHub enables organizations to build a shared language for data governance. Whether through automated RDF/YAML ingestion or manual UI management, the system ensures that every business concept is discoverable, well-defined, and correctly mapped to technical data assets.