Governing the catalog without leaving the portal

What you will take away from this lesson

206 - Knowledge: from a memory to something the whole team can use named two places a promoted fact can land, and spent its time on one of them: the canonical knowledge page. This lesson is about the other one. The catalog is not only a sink that writes arrive in; it is a set of vocabularies somebody has to define, keep current, and occasionally retire.

All of that now happens inside the portal. The tag vocabulary, the domains the estate is grouped into, the business glossary, the context documents, and per-table metadata are edited on the same page where the agent's work lands, under the same persona rules, in the same audit log.

Learning Objectives

01State the rule that decides what appears under Catalog: everything under it is DataHub, and anything the portal’s own database backs stays outside it.
02Name the five inner tabs, and say which of them are the described things and which are the vocabularies that describe them.
03Describe what editing a table covers in the portal, and why DataHub offers no table create or delete.
04Explain what the Tags, Domains, and Glossary tabs govern: the vocabulary itself, rather than what any one table happens to carry.
05Say what a delete states before it runs, and why a glossary node that still holds entries is offered no delete at all.
06Name the two conditions that must both hold before any write is permitted, and where every permitted write is recorded.

Where we are in the curriculum

If any term in this lesson feels unfamiliar, the 100 series is one click back. The 200 series assumes that mental model.

100 Series: the foundation

Open index

If a term in this lesson looks unfamiliar, back up to the 100 series. The 200 series assumes that mental model. Every row above is a direct link.

Why this belongs in the portal at all

The rule that decides what lives here

A catalog surface in a product that also stores its own knowledge has an obvious way to go wrong: two piles of similar-looking things with no stated boundary between them, and a user who has to guess which pile holds the thing they want. The portal avoids it with a rule you can hold in one sentence.

Everything under Catalog is DataHub. Anything the portal keeps in its own database, knowledge pages and the changesets that record promotions, stays outside it. Once you know the rule you can predict where any new surface will appear without being told.

One rule decides what appears under Catalog

Everything under Catalog is DataHub

Tables: The datasets the connection catalogs, and their metadata
Context Docs: Markdown notes attached to a catalog entity
Tags: The tag vocabulary itself
Domains: The business areas the estate is grouped into
Glossary: The terms your organization defines, and the nodes that hold them

Anything the portal's own database backs stays outside it

Knowledge pages: Canonical prose, versioned by the portal
Changesets: The record of what a promotion wrote, and the rollback for it
Insights and memory: The review queue, and what is still personal

That rule is why the top row stays at four tabs while the catalog surfaces grow underneath it. A new governance surface is a new inner tab, not a new place to look.

Five tabs: the things, then the words for them

Catalog holds its own inner tabs, and the order they appear in is the order they are best read in. Tables and Context Docs are the described things. Tags, Domains, and Glossary are the vocabularies that do the describing, and each of them governs the vocabulary itself rather than the copy of it that any one table happens to carry. That distinction is the thing most worth taking away from this lesson: the Tags tab is not a list of the tags on the table you were just looking at.

Five inner tabs, in the order they are read

Tables
Described thing
Browse or search what the connection catalogs, and open one for its description, tags, owners, glossary terms, domain, and columns.
Context Docs
Described thing
Markdown notes attached to a dataset, a glossary term, a glossary node, or a container. Longer than a description and anchored to the thing it explains.
Tags
Vocabulary
The tag vocabulary itself: what tags exist, what each one means, and which tables carry it.
Domains
Vocabulary
The business areas the catalog is grouped into, and which tables belong to each.
Glossary
Vocabulary
The terms your organization defines and the nodes that organize them, walked as a tree one branch at a time.

The DataHub connection is picked once, at the top of the section, and applies to every inner tab. Switching it returns each tab to its list, because an open table, document, tag, domain, or term belongs to the catalog it was read from.

What it looks like

The portal Catalog tab: the Tables, Context Docs, Tags, Domains, and Glossary inner tabs with a connection picker on the right, above a searchable list of catalogued tables with their descriptions and tags — The Catalog sub-tab, open on Tables. The connection picker sits at the top right and governs every inner tab beneath it. The section is addressable at `/knowledge/catalog`, the inner tab rides in the hash, and a single entity stays addressable on its own, which is what a catalog reference chip links to from anywhere else in the portal.

Tables: metadata editing, not table lifecycle

The Tables tab browses or searches what the connection catalogs and opens one dataset at a time. Everything on that screen is the metadata the next person reads before they trust the data: what it is, who owns it, what it has been labelled with, which business area it belongs to, and what each column means.

Editing one table's metadata

What an open table shows
Its description, tags, owners, glossary terms, domain, and columns. With datahub_update granted on a write-enabled connection, each of those facets is editable in place; without it, the same view appears with no editing controls.
Names, not identifiers
Tags, glossary terms, and domains are chosen through a name-search picker. Type Reven, select Revenue, and the identifier is resolved for you. Attaching a term never means knowing the URN the catalog generated for it.
Descriptions are markdown
Table and column descriptions render formatted, and the editor is the same split source and preview editor used for knowledge pages and prompts. A description can carry a list of caveats rather than one run-on sentence.
Owners are checked
An owner is a DataHub user or group identifier, and an invalid one is rejected with a visible inline error rather than accepted and silently dropped.
No create, no delete
DataHub has neither, because tables originate in the source systems that produce them. This tab is metadata editing, not table lifecycle, and the distinction is worth holding on to: nothing here can drop a dataset.

Context Docs: the explanation that outgrew a description

A description is one field, and some things do not fit in one field. A context document is a markdown note attached to a dataset, a glossary term, a glossary node, or a container: the migration history behind a column that has two meanings depending on the date, the reconciliation procedure a table is part of, the reason a metric was redefined in March. Browse or search them, open one to read it rendered, and with the matching grants create, edit, and delete them through the same markdown editor used everywhere else in the portal.

The attachment is the point. A note in a wiki about a table is a note somebody has to find. A note attached to the table arrives with the table.

Tags and Domains: governing the words themselves

These two tabs answer questions a per-table view cannot. What does certified actually mean here, and who decided? Which tables are in Finance, and which one moved out of it last week? Both tabs list the connection vocabulary with descriptions, filter by name, and open one entry to see what it means and what carries it, with every carrier linking straight back into the Tables editor.

Governing the vocabulary rather than one table's copy of it

Glossary: the definitions the business argues about

The glossary is where the words that cause the most expensive misunderstandings get written down. Active customer, net revenue, fiscal quarter: terms every team uses confidently and no two teams define identically. It is a tree rather than a list, because a real glossary has structure, and the portal walks it one branch at a time rather than flattening thousands of terms into a scroll.

Five things an open term shows

Its definition
Markdown, edited in the split source and preview editor, so a definition can carry a heading, the cases it includes, the cases it excludes, and a worked example. That is the difference between a glossary somebody consults and one they stop trusting.
Where it sits
A breadcrumb built from the catalog’s own parent chain, so it reads the same however you arrived at the term.
Its context documents
The markdown notes attached to this term, for the material too long to be a definition.
The knowledge pages that reference it
The reverse of the citation a page makes. A steward reading a term sees what has been written about it without going looking.
The tables annotated with it
Each links into the Tables tab editor, and the ones where a column rather than the table carries the term are marked separately. Listing only the first would report every carrier as a column carrier, which is a different claim entirely.

The glossary is a tree, so it is walked one branch at a time: the root holds the nodes and the terms with no parent, and opening a node shows what is inside it. A node is both a place in the tree and an entity of its own, so browsing into one is its detail view. One glossary backs both surfaces: a term defined here is immediately what the Tables tab picker offers.

What a delete tells you before it runs

Retiring a definition is the operation with the widest reach and the least visible consequence, which is a bad combination. Every delete in these tabs states what it is about to affect, in the units you would ask about, before you confirm.

The design principle underneath is worth naming: when the outcome of an action cannot be stated honestly, the action is not offered. That is a stricter rule than warning about it, and it produces one case where a button you might expect is simply absent.

Every delete states its blast radius first

Retiring a tag
Says how many tables in the connection carry it, so retiring an unused tag and retiring one the warehouse depends on do not look identical.
Retiring a domain
Says how many tables are in it, and that they will be left without a domain, because the delete removes the definition and touches no table.
Retiring a glossary term
Says how many tables are annotated with it, and that the annotation stays. Removing the definition does not remove the term from the tables carrying it.
A glossary node that still holds entries
Is offered no delete at all. The catalog would take the node without taking its contents, so the honest options are to empty it first or leave it, and the tab says which. A confirmation that cannot state its outcome is worse than no button.

Two gates on every write

None of this introduces a governance model of its own, and that is the most important thing about it. A write to the catalog from the portal passes exactly the checks a write from an agent passes, because they are the same checks.

Two conditions, both required, before anything is written

The persona grants the tool
Creating needs datahub_create, editing needs datahub_update, retiring needs datahub_delete. Reads need only DataHub access, which is why a persona without the write grants sees exactly the same browsing surfaces with no editing controls rather than a tab full of buttons that fail.
The connection is write-enabled
A connection marked read-only refuses writes no matter which tools the persona holds. Granting a capability and pointing it at a catalog you are willing to have changed are two separate decisions, and both have to be made.
Both are checked on the server
The checks do not depend on what the interface chose to render. A request that reaches the API without both conditions is refused there, and every permitted write is recorded in the audit log alongside the tool calls.

These are the same tool grants an agent is subject to. A steward editing a domain in the portal and an agent writing a description through apply_knowledge pass the same check and land in the same log, which is what makes the audit trail one trail.

One behavior to expect

Where this leads

A catalog is worth governing because of what reads it. Every question an agent answers passes through the descriptions, tags, domains, and definitions on this screen, so the work of keeping them accurate is not administrative overhead sitting beside the useful work; it is the input to it.

Key terms

Eleven terms cover the vocabulary of catalog governance. Three of them are tool names (datahub_create, datahub_update, datahub_delete), and they are the ones that decide what any given person sees when they open these tabs.

Key Terms

Catalog (the portal tab): The whole of your data catalog inside the portal, and the second of the two knowledge sinks. Its contents are DataHub and nothing else; the surfaces the portal backs with its own database live beside it rather than inside it.
Connection: The configured catalog a tab is reading from, picked once at the top of the section and applied to every inner tab. Switching it returns each tab to its list, because an open entity belongs to the catalog it was read from.
Write-enabled connection: A connection not marked read-only. It is the second of the two conditions a write must satisfy; the first is the persona grant. A read-only connection refuses writes regardless of what the persona holds.
Tag: A short label attached to tables and columns, defined once in the tag vocabulary and carried by many entities. Its description is plain text rather than markdown, because that is how the rest of the catalog renders the field.
Domain: A business area the catalog is grouped into. A table has at most one, so adding a table that already has a domain moves it rather than giving it a second.
Glossary term and node: A term is a definition your organization stands behind; a node is a branch that holds terms and other nodes. Both carry markdown definitions, and both are reached by walking the tree rather than through a flat list.
Context document: A markdown note attached to a dataset, a glossary term, a glossary node, or a container. It is where the explanation too long for a description goes, anchored to the entity it explains.
URN: The identifier the catalog generates for an entity. It is what a reference actually stores, and it is deliberately something you never have to type: every picker in the catalog searches by display name and resolves the identifier for you.
datahub_create / datahub_update / datahub_delete: The three tool grants that gate catalog writes, one per kind of write. They are ordinary persona grants, checked the same way as every other tool covered in 207, which is why the portal needs no governance roles of its own.
Blast radius: What a delete states before it runs: how many tables carry the tag, are in the domain, or are annotated with the term, and what happens to them afterwards. Where the outcome cannot be stated honestly, as with a glossary node that still holds entries, no delete is offered.
Backlink: The list of knowledge pages that reference a tag, domain, or glossary term, shown on the entity itself. It is the reverse of the citation a knowledge page makes, and both directions omit anything the reader cannot access.

211 - Governing the catalog without leaving the portal