Building a glossary that grounds

If terms, bindings and approval are new to you, start with Why your AI agent gives different answers.

A glossary that reaches the data

We call it grounding. A term is grounded when its typed relationships lead to a column or table a role can query. The path runs from a broader term to narrower ones. "Revenue" reaches data through its parts, order amount and refund amount, and the columns they bind to. "Customer" reaches it through "enterprise customer", a kind of customer. "Customer tier" reaches it through "platinum", one of its valid values. A synonym leads both ways, because the two words mean the same thing.

A term never borrows a sibling's data. Climbing to a shared parent and coming back down doesn't count, so "invoice" doesn't reach the data of "purchase order" just because both are kinds of document.

Provisa computes grounding from the live model. Register a table, rename a column, retire a term or remove a relationship, and every term on the affected paths is traced again. Nobody maintains a status field by hand. When a term stops reaching data, its page says so at once.

Draft or final

A term's chip reads grounded when a path reaches data through approved terms only. It reads ~grounded when every path still passes through a draft, and it turns final the moment a steward approves the draft on its path. A term with no path to data gets no chip. With no term open, the stewardship summary lists the ~grounded terms each waiting on one approval, and the approved terms that reach no data.

Verified context for agents

More metadata helps an agent only when the metadata is right. Through Provisa, an agent sees the terms on paths to data, and only on paths an approved term anchors. A draft it sees is marked as a draft. A term nobody has defined appears as an unnamed step along the way. So every term the agent uses has been shown to reach a column or table its role can query, and the check runs again whenever the model changes.

Guidance while you build it

The commonest glossary mistake is easy to make. Two terms obviously belong together, no sharper relationship comes to mind, and they get linked as "related to". Provisa steps in at the moment you choose a relationship, while the fix is still cheap.

Each relationship type has a test

The type picker shows each type's test beside it, and the relationship assistant applies the same tests when it proposes links.

• Kind of. Every X is a Y. Every enterprise customer is a customer.
• Part of. A Y has an X. An order has an order amount.
• Valid value of. X is one of Y's allowed values. Platinum is a customer tier.
• Synonym. X and Y mean the same thing. Client and customer.
• Related to. X and Y are distinct topics that go together, and neither is a kind, a part or a value of the other. Cake and candles.

"Related to" holds a place

The first four types ground. "Related to" doesn't, so a term linked only by "related to" still can't reach data. Treat each one as a placeholder for a pair you haven't resolved yet. When two terms go together and no grounding type fits, the assistant proposes "related to" with a note that the pair may want resolving. A filter on the term list shows every term with a "related to" link, so you can find the placeholders and work through them. A term that reaches no data and has only "related to" links says so on its page. It's guidance. Nothing blocks you.

Choosing "related to" opens the alternatives

Pick "related to" for a link you're adding and Provisa interrupts, briefly. A dialog explains why it's the least useful link you can add, then draws every shape that would ground the pair with one new term, tightest first, each with a suggested name. For cake and candles it offers these.

Choose a shape and the new-term form opens with the name and both links filled in, for you to confirm or rename. You can still add "related to" in one click, and it joins the placeholders the filter lists. When the assistant proposes links in bulk, each "related to" it proposes carries the same shapes in its note. The assistant proposes the structural types first and never adds a term on its own. Whether a pair needs a new term, and what to call it, is your decision.

The broader the new term, the less its grounding tells you

Why tightest first? "Party" grounds candles as surely as "cake decoration" does. A hub that broad leads to everything at a party, though, so its grounding no longer says which data answers a question about candles. A tight term gives the agent a short path to the right columns. A hub gives it a long path to many.

Terms from your documents

Most of what a business means by its words is already written down, in policies, processes and regulations. Provisa reads those documents for you. Choose a document from your reference library, or give it a new one as a file or a link, and it proposes the concepts the document defines and uses.

• One concept, one term. "Client", "customer" and "CX" in the same policy become one proposed term, with the other two as synonyms.
• One word, two meanings, two terms. A word the document uses one way in Section 2 and another way in Section 9 becomes two candidates, each tied to its own passages.
• The document's own definition first. An explicit definition, such as "Client means…", becomes the term's definition. Where the document has none, a definition is drafted, marked as drafted, and lists every passage it drew from. Explanations that disagree are shown side by side. They are never blended.
• No duplicates. A candidate that matches a term or synonym you already have is offered as a merge.
• Relationships next. The new terms go straight to the relationship assistant, with the same guidance toward relationships that ground.

Every proposal cites the passage it came from, by document, section or page, and quoted text. Nothing joins the glossary until a steward accepts it.

A reference library

The documents you scan stay after the scan, in a reference library: the policies, processes, regulations, contracts and specifications that matter to your work in Provisa. Polly answers from it, agents reach it over MCP, and the glossary draws on it when it drafts a definition or proposes a relationship. Whatever uses a passage cites it.

Each document belongs to domains, or to the whole organization, the same as a term. An assistant working for a role reads only the documents that role may read. A document added by a scan arrives as proposed, and the steward decides whether to keep it. Admins maintain the library on its own page. They add a document, refresh one from its link, upload a new version or remove one.

Nothing is re-reviewed behind your back when a document changes. Whenever you're improving the glossary, scan a library document again. You see what's new and what you already have, with the passages, and you decide.

Quality you can measure

Glossary work often falls to people who were never taught how to build one. They know the business, and the result can look finished while it sends agents to the wrong data, or to none. The Ontology quality report, one of Provisa's standard reports, shows whether the glossary is any good. It measures the glossary from the model itself, by domain and by steward.

• Grounded share. The terms in service that reach data, with draft and final grounding counted apart.
• Approved and grounded share. The terms an agent may use as a route to data.
• Unresolved placeholders. The "related to" links, and the terms whose only links are "related to". Each row opens its review.
• Grounding precision. How many hops lie between a term and its data, and how many paths pass through a broad hub term.
• Grounded only through drafts. Each term that waits on an approval, with the term whose approval makes its grounding final.
• Undefined terms on paths to data. Terms an agent passes through with no definition to read.
• Drift. The terms that lost or gained grounding since the previous period.

Every row links to its term. You read the report through the same governed pipeline as any other data, as the roles you select, and export it to the BI tool you already use.