How to set up an OpenMetadata business glossary and domains
Most data teams reach this point the same way: finance and sales both report a figure called revenue, the two numbers differ, and nobody can say which owner signs off on the definition. OpenMetadata supports glossaries, classifications and domains as documented features, so the platform side of the problem is manageable. The real work is agreeing what each term means, naming who owns it, and deciding who keeps it current after the catalog goes live. A team usually needs this in one of three situations: before a catalog rollout, when the catalog will be the place where people look up definitions; during a governance program, when a steering group has committed to shared terminology; or when an audit or regulator asks who owns a metric and how it is calculated. In each case, the glossary and domain structure should exist before large volumes of tables and dashboards are attached to them. Attaching assets to undefined terms creates cleanup work that grows with every connector you add. OpenMetadata is released under the Apache License 2.0 and is maintained by Collate, which also offers commercial enterprise capabilities and premium support. Confirm with Collate and in your own deployment which features you will use, because the open-source edition and the commercial offering differ in scope. Your license review and support decision should be made before you depend on any capability that sits in the commercial tier. Before building anything, decide three things with the business owners, not only the platform team. First, the domain model: which business areas own which data, such as finance, customer or product. Second, the glossary scope: which terms are enterprise-wide and which belong to one domain. Third, the owner for each term, with a named person who can answer questions and approve changes. Write these decisions down in a short standard that states the term format, required fields such as definition and owner, and how disputes are settled. This document will do more to prevent drift than any configuration screen. After go-live, the glossary needs a maintenance rhythm. Assign a steward who reviews change requests, retires terms that no longer apply, and checks that linked assets still reflect the approved definition. Ask your implementation partner and internal team to define who is accountable for this work, how much time it takes each month, and whether it will be handled internally or under a support retainer. Those answers determine whether the glossary stays accurate a year from now.
Domain and glossary design options and when each fits
This table compares the main design choices for OpenMetadata glossaries, domains and data products, with the typical fit, main risk and items to verify for each option. Most organizations combine options across these choices, so read each row as one part of the overall model. Confirm each feature against the documentation for your version before you commit to a structure.
| Design choice | Typical fit | Main risk | What to confirm in the running version |
|---|---|---|---|
| One organization-wide glossary | Small or mid-sized catalogs with one data owner group and a shared vocabulary for finance, risk and reporting | Slow approvals as every term change queues behind one reviewer group | Confirm how term review and approval workflows are configured and who can edit terms |
| Glossaries per domain | Large organizations where business units use the same words with different meanings | Duplicate terms and conflicting definitions across domains | Confirm how terms can be linked across glossaries and whether cross-domain synonyms are supported |
| Domains aligned to business units | Organizations where budgets, accountability and reporting already follow business units | Shared datasets with no clear owner between two business units | Confirm how a data asset is assigned to one domain and whether shared assets can be tagged to several |
| Domains aligned to data platforms | Platform teams that run the warehouse, lake or streaming estate as a service | Business users cannot find data by the business area they work in | Confirm how domains appear in search and whether business-facing views can be filtered differently |
| Data products grouped by consumer | Teams that publish curated datasets for specific reports, models or customers | Duplicate products built for similar consumers with no single owner | Confirm how data products are defined, versioned and linked to their input tables and dashboards |
| Data products grouped by source system | Teams that own ingestion from one application and expose its data to many consumers | Consumers must learn each source's structure before they can use the data | Confirm how source-level and consumer-level products can be linked and which one carries ownership |
How domains, data products and glossary terms relate
Three objects in OpenMetadata do different jobs, and getting their roles straight before you load any content prevents most of the later confusion. A domain groups assets and the people who own them, usually along a business area such as payments, risk or customer onboarding. A glossary term defines a business concept, such as "active customer" or "net exposure", in one place. A data product collects the assets a particular consumer needs for a specific purpose, such as a monthly regulatory extract or a churn model's input set. The domain answers who is responsible for this data, the term answers what this concept means, and the data product answers what a consumer should use and where to find it.
A glossary term becomes useful when it is linked to the tables and columns that carry the concept. In practice, a data steward attaches the term "active customer" to the status column in a customer table, and to the matching field in a reporting view. Anyone who opens either asset then sees the same definition and the same owner, so a dashboard author, a pipeline developer and an auditor are reading one agreed meaning rather than three local interpretations. The check to run after the first links are made is simple: pick a term, open the assets it is attached to, and confirm that each one points back to the same glossary entry rather than a copy of its wording.
Before you design the structure, confirm three points against the documentation for the version you deploy, because the supplied facts confirm only that glossaries and domains are supported. First, the exact relationship model: how a term attaches to tables, columns and data products, and whether a term linked at one level is shown at child levels. Second, inheritance rules: whether an asset in a domain inherits that domain's owners, and whether a data product's assets inherit the domain they sit in. Third, approval workflows: whether term changes or new terms can be routed for review, and who can approve them. Write down your answers to these questions before importing terms, because changing the model after content exists means rework across every linked asset.
Setting up domains and glossary terms in OpenMetadata
This sequence takes a running self-hosted OpenMetadata deployment from empty to a governed set of domains, glossary terms and owners. Each step ends with a check that the work is visible where people will use it. The order matters because permissions and asset links depend on the owners and domains agreed first.
Confirm the deployment is ready
Setup depends on a running self-hosted OpenMetadata instance, so start by confirming it is healthy and reachable by the people who will govern it. For bare metal installs, review the prerequisites in the bare metal deployment docs, including Java 21, PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x. For Kubernetes, follow the Kubernetes deployment docs. Confirm the exact versions for your release before you begin. Done when you can sign in as an administrator, open the Domains and Glossary areas, and see an empty but working catalog.
Agree the domain map and owners
The data governance lead and the business leaders for each area agree which business domains will exist, which teams hold the data in each, and who answers for its definitions. Record one named owner and one backup per domain, and confirm that each owner accepts the role in writing. Every team that holds data should appear in exactly one domain. Done when the map is signed off, every domain has an owner who has accepted the role, and the unassigned teams list is empty.
Define glossary structure and naming rules
Decide how the glossary will be organized, for example by domain or by business process, and how deep the term hierarchy may go. Write naming rules that cover capitalization, singular or plural forms, approved abbreviations, how synonyms are recorded, and how retired terms are marked. Test the rules with a short list of candidate terms drawn from two or three groups that will use the glossary. Done when the rules fit on one page and each candidate term can be named the same way by two reviewers without further discussion.
Load an initial set of terms
Stewards load a first set of terms, each with a plain-language definition, a named owner and the domain it belongs to. Start with terms that appear in reports, contracts and regulatory filings, because disagreements about meaning are most likely there. Ask each owner to review the definition before it is published, and record any open questions on the term itself. Done when every loaded term has a definition, an owner and a domain, and each owner has confirmed their entries.
Assign domains to existing assets
Link existing tables, dashboards and pipelines to their domains, and connect the relevant glossary terms to the columns and assets they describe. Check the bulk assignment options for your release in the OpenMetadata documentation before choosing between manual edits and scripted updates through the API. Then open a sample table from each domain and confirm it shows the expected domain and its linked term. Done when each sample asset shows the correct domain and term, and a list of unassigned assets is kept for follow-up.
Set who can create and edit terms
Configure roles and policies so that approved stewards can create and change glossary terms and domains, while other users can view them and suggest changes. Map these roles to the teams agreed in the domain map. Confirm the permission model for your version in the OpenMetadata security and governance documentation before applying it to production. Done when a steward can edit a term, a domain owner can edit only their own domain, and a test account without a governance role has read-only access.
Verify owner views and hand over upkeep
Sign in as each domain owner and confirm they can see their domain, its assets and the terms waiting for review. Check which notifications each owner receives when a term they own changes, and adjust the settings if the owner does not get the expected alert. Write down who maintains the glossary after go-live, how often definitions are reviewed and who approves new terms. Done when each owner has confirmed their view in writing and the maintenance contacts are recorded in the governance runbook.
Access control and SSO for domain and glossary edits
Who can change a glossary term or domain depends on how people sign in, which roles they hold and how the platform is kept running. The cards below cover the identity decisions to make before go-live and the operational routines that keep those edits traceable and recoverable.
Choose the identity provider
OpenMetadata documents SSO with Auth0, Azure, Google, Okta, Amazon Cognito, OneLogin, Keycloak and custom OIDC providers. Choose the provider that already holds your workforce groups, since those groups are the natural starting point for deciding who may edit domains and terms. Confirm the setup steps for your provider in the OpenMetadata security documentation, then test sign-in with an account from each group before inviting editors.
Plan for a single authentication mechanism
OpenMetadata does not support combining SSO with basic authentication, so the platform runs on one sign-in mechanism at a time. This affects administrator access, service accounts used by ingestion and automation, and any local accounts created during a trial. Inventory these accounts before cutover, decide how each will authenticate under the chosen mechanism, and confirm in the security documentation how bots and API tokens are handled.
Map roles to glossary and domain ownership
Roles and permissions in OpenMetadata determine who can create, edit and approve glossary terms and domains. Default roles may not match your stewardship model, so draft a matrix showing who owns each domain, who may propose terms and who may approve them. Confirm the role and permission details in the security documentation, then test each role against that matrix in a non-production environment.
Audit trails for term and domain changes
Glossary and domain changes only support governance if you can reconstruct who changed a definition, owner or domain assignment, and when. Confirm what OpenMetadata records for these edits in your release, how long those records are kept, and whether they can be exported to your SIEM or log archive. Run a test change, then check whether the record shows the actor and the values your reviewers need.
Back up the metadata database and search index
OpenMetadata stores metadata in a relational database and indexes it in a search engine. The documented bare metal prerequisites are MySQL 8.0.42 or later or PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x. Back up the database, confirm how the search index is restored or rebuilt, and run a restore test that includes glossary terms, domains and their owners. Record the recovery steps in your runbook.
Keep the platform on a supported release
OpenMetadata 2.0.0 was released on August 24, 2026, with maintenance releases 2.0.1 to 2.0.5 following about every one to two weeks. The 2.0 release notes list breaking changes, including moving embedding credentials into an llmConfiguration block, a new Databricks auth format, rebuilding custom ingestion images for Python 3.12 and migrating Great Expectations to 1.3 before upgrading. Test each upgrade in a non-production environment and read the release notes first.
Who maintains glossary terms and domain owners after go-live
The decision you must make before go-live is who keeps the glossary and domain ownership accurate once the first load is finished. In OpenMetadata, that work sits across four roles: named domain owners who are accountable for each domain and its data products, term stewards who approve and maintain individual glossary terms, a catalog administrator who controls the platform itself (users, roles, glossary structure, and ingestion), and a review cadence that decides when new terms are accepted and when retired definitions are removed. Write these roles down with a named person for each, not a team alias, because a term without a steward has no one to answer when a definition is challenged.
The most common failure is not a bad initial load. It is drift. The glossary is populated from workshops, approved, and then the underlying work moves on: a warehouse schema is renamed, a source system is replaced, a finance team splits a metric into two definitions, and the term in the catalog still describes the old state. Analysts then find terms that disagree with the tables they query, and trust in the catalog falls quickly. Ask each steward to name the systems and tables their terms depend on, and treat a rename or retirement in those systems as a trigger for a glossary review, not something to fix later.
Upkeep can sit with an internal team or with an external partner, and the choice depends on whether your organization has someone who can make business decisions about definitions. An internal team usually needs a named catalog administrator with time allocated to the role, plus stewards inside each business area. A retained support arrangement can handle platform tasks such as upgrades, connector maintenance, access reviews and checking that ingestion still runs, while your stewards keep ownership of the definitions themselves. DeployOpen offers ongoing support and retainers for self-hosted OpenMetadata. Ask any partner to separate in writing what it maintains from what your business stewards must decide.
Whichever model you choose, write the upkeep responsibilities into the handover document before the project closes. The handover should list each domain owner and term steward by name and role, the review cadence for new terms and retirements, who approves changes to the glossary structure, who receives alerts when a connector or ingestion job fails, and how a steward is replaced when someone leaves. Confirm these items with your own team and, where a retainer is involved, with the support provider. Without them written down, the glossary will age in the same way a spreadsheet glossary does, only inside a tool that looks maintained.
What to confirm before rolling out glossaries and domains
Glossary and domain decisions are easiest to get wrong when assumptions about versions, workflows and sign-in go untested. The cards below cover the version you run, how the 2.0 upgrade affects existing workflows, where documented knowledge now lives, whether intake forms are needed, which connectors carry linked assets, and how users sign in. Confirm each one in your own environment before agreeing on a plan.
Running version and patch level
Record the exact OpenMetadata version your environment runs and the patch level you will target before writing the glossary and domain plan. OpenMetadata 2.0.0 was released on August 24, 2026, and maintenance releases 2.0.1 to 2.0.5 have followed about every one to two weeks. Check each release note against the features your stewards depend on, and agree on one version for the rollout so testing and production match.
Upgrade impact on workflows
Check whether moving to 2.0 changes how glossary terms, domains and data products are created, approved or edited in your installation. The published breaking changes cover embedding credentials, the Databricks auth format, custom ingestion image rebuilds for Python 3.12 and the Great Expectations 1.3 migration. They do not name glossary or domain workflows, so test those flows in a staging copy using your own term approvals and domain assignments before production cutover.
Knowledge Center and Context Center
OpenMetadata 2.0 replaced the Knowledge Center with the Context Center, so existing documented knowledge needs a deliberate home. Inventory the descriptions, runbooks and business context your teams have written, confirm how they appear after upgrade, and decide whether each item belongs in a glossary term, a domain page or an asset description. Confirm in staging how existing content is carried across, since unmigrated knowledge can become hard to find.
Custom intake forms
OpenMetadata 2.0 added custom intake forms for structured requests. Decide whether requests for new terms, domain changes or data product ownership need a form with required fields, or whether the default workflow is enough. If you use forms, write down the fields a requester must supply, such as domain, steward and definition, who may submit each request, and who approves it. Confirm how forms are configured and which roles can edit them in your version.
Connector scope for linked assets
Terms are only useful where they can be linked to assets, so list the warehouses, BI tools, pipelines and ML platforms that will carry glossary links. OpenMetadata lists more than 130 connectors, but each connector has its own documented scope and stage. For every source, confirm that it ingests the tables, columns, dashboards or pipelines you need to link, and that the glossary terms you plan to assign are supported on those asset types.
Single sign-on and login limits
OpenMetadata documents SSO with Auth0, Azure, Google, Okta, Amazon Cognito, OneLogin, Keycloak and custom OIDC providers. It does not support using multiple authentication mechanisms at once, such as combining SSO with basic authentication. Decide early how stewards and domain owners sign in, how access is removed when roles change, and how administrators recover access if the identity provider is unavailable. Confirm this approach against the security documentation for your version.
Questions buyers ask about OpenMetadata glossary and domain rollouts
How much effort does an OpenMetadata glossary and domain setup take?
Effort depends mainly on four drivers: the number of domains, how many terms conflict across teams, how many sources you connect, and how complex your approval rules are. Each domain needs an accountable owner, a defined scope and agreed terms. Terminology conflicts usually take the most time because resolving them is a business decision, and no configuration setting makes that decision for you. Approval rules add design and testing work, since each status change needs a tested path. Every connected source adds ownership assignments and links between tables and glossary terms, so a large estate multiplies that work. DeployOpen does not publish prices. Ask for a written scope that lists domains, the approximate number of terms you expect to load, the sources in scope and each approval path. The quote follows from that scope.
How long does an OpenMetadata domain rollout take?
Duration follows the same drivers as effort, plus how quickly your people can make decisions. Projects move fastest when named owners approve terms within an agreed review cycle. Infrastructure readiness is the other dependency. A production deployment needs its platform components in place first. The bare metal documentation lists Java 21, MySQL 8.0.42 or later or PostgreSQL 15 or later, and Elasticsearch 9.x or OpenSearch 3.x as prerequisites. If any of these must be procured, approved or built, that lead time sits outside the glossary work. No duration is quoted here. Ask for a timeline in the written scope, with milestones tied to client decisions and the environments each milestone requires.
What do we need to provide for a glossary project?
Plan for four inputs: named owners, subject matter experts, access to sources and a test environment. Named owners are accountable people for each domain who can approve or reject terms and settle ownership questions. Subject matter experts supply definitions and resolve disagreements between teams, usually in short review sessions. Access to sources means read permissions on the warehouses, BI tools and pipelines you plan to connect, plus service accounts for ingestion, with credentials handled through your own secrets process. A test environment lets the team load sample terms and check approval flows before production. Confirm these inputs in writing during scoping, because missing owners are a frequent reason review cycles stretch out.
Can our internal data team set up OpenMetadata domains alone?
Yes, an internal team can do it alone if it has the platform skills, the time and the business decisions already made. OpenMetadata is released under the Apache License 2.0, so the software itself carries no license purchase. The work does require people who can run the platform, which means Kubernetes or bare metal operations, database and search administration, and upgrades. It also requires people who can configure connectors and use the REST APIs, the Python SDK or other language libraries for bulk loading. Collate maintains OpenMetadata and offers commercial enterprise capabilities and premium support, so check whether you need any of those. If internal capacity is thin, a partner can take the build while your team keeps the governance decisions. Decide which parts you would hand over before you request a scope.
What ongoing upkeep does an OpenMetadata glossary need?
Upkeep has two parts: governance work that continues after go-live, and platform maintenance. Governance includes reviewing terms on a schedule, updating owners when people change roles, and onboarding new sources into the right domain. Platform maintenance covers patching, backups and upgrades. OpenMetadata 2.0.0 was released on August 24, 2026, with maintenance releases 2.0.1 to 2.0.5 following about every one to two weeks, so plan for a regular patch cadence. The 2.0 release notes list breaking changes, including moving embedding credentials into an llmConfiguration block, a new Databricks auth format, rebuilding custom ingestion images for Python 3.12, and migrating Great Expectations to 1.3 before upgrading. Assign an owner to each task. DeployOpen offers ongoing support, upgrades and testing as retainers, and the scope of any retainer is agreed in writing.
How should we sequence domains and glossary terms during rollout?
Start with one or two domains that have clear owners and heavily used tables, then expand once the approval flow works in practice. Illustrative example: a finance domain with three accountable owners and a short list of contested terms can prove the review cycle before marketing or operations domains are loaded. Resolve the conflicting terms early in each domain, because they hold up every later step. Load sources in the same order as the domains they serve, so each table has an owner and linked terms from the start. Keep a log of decisions and who made them, since auditors and new staff will ask. Ask the provider to show the sequence and the exit criteria for each phase in the written scope.
Does OpenMetadata support single sign-on for glossary owners?
Yes, OpenMetadata documents SSO with Auth0, Azure, Google, Okta, Amazon Cognito, OneLogin, Keycloak and custom OIDC providers. Owners who approve terms can sign in with the identity provider your organization already runs. One limit matters for planning: OpenMetadata does not support using multiple authentication mechanisms at once, such as combining SSO with basic authentication. Decide early how administrators will sign in, including the break-glass path if the identity provider is unavailable. Confirm the configuration steps for your OpenMetadata version against the security documentation, and test the sign-in flow with a sample owner in the test environment before production.
How DeployOpen works on this
DeployOpen plans, builds and documents OpenMetadata business glossary and domains inside infrastructure you control, from the first domain map to the day your stewards take over. Engagements are fixed-scope, with the work, deliverables and timeline agreed in writing before any build begins.
How we scope
- The written scope lists the domains, glossary terms, owners and stewards to be configured in your OpenMetadata instance.
- Scope names which data assets are linked to glossary terms and which data products each domain will own.
- We agree how existing glossaries and spreadsheets will be reviewed, mapped and imported before any import runs.
- Deployment target, such as Kubernetes or bare metal, is confirmed in scope so governance work matches your environment.
How we build
- We model domains, data products and glossary hierarchies in a non-production instance before loading production content.
- Access roles for domain owners, glossary reviewers and stewards are configured through your chosen identity provider.
- We test term approval workflows and ownership assignments against sample assets from each domain.
- Glossary imports and API-driven updates are scripted with the OpenMetadata REST APIs or Python SDK so changes are repeatable.
How we hand over
- You receive a written record of domain ownership, term definitions, approval steps and the named people responsible for each.
- Runbooks explain how to add a term, retire a term and reassign a domain without breaking linked assets.
- Your team is walked through the approval workflow and the review cadence agreed for glossary changes.
- Configuration is documented so your staff can reproduce the setup after a platform upgrade or restore.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Upgrades that touch glossary or domain data are planned against the OpenMetadata 2.0 breaking changes before they run.
- Your stewards decide who maintains terms after go-live. We can document that model and support it under a retainer.
- Scope for any later glossary expansion or new domains is agreed in writing as a separate, fixed-scope change.
