BUILDING Parts of this page describe what is not built yet, and each says so.

Stewardship

Stewardship is the part of Governance that says who looks after the data. It has domains, which are business areas of your data, owners and stewards, who are people named for a domain or for an asset, and certification, a mark that a table or a view can be relied on. It reads the whole organisation, whichever project is selected in the console. A steward is an assignment, not a role, and being one grants no access to data.

Domains

A domain is a business area of the organisation’s data, such as Sales or Finance. It belongs to the organisation and not to a project, so it reaches across every project. Each domain has a slug, which is its short name and never changes once the domain exists (it starts with a lowercase letter and holds lowercase letters, digits, hyphens and underscores, up to 63 characters), a display name of up to 100 characters, and a description of up to 1000. Owners and admins create domains and change them.

A domain covers assets that you name: a layer, a schema, a table or a view. An asset belongs to the domain that covers it, else to the domain that covers its schema, else to the domain that covers its layer, and it belongs to at most one. A cover names an asset by its project, its kind and its name, so it applies in every environment of the project: covering silver.sales.orders in dev covers the one in prod too. A name that only one environment declares is covered there and nowhere else. Because a cover is by name, a table renamed in git is no longer covered, and the domain says how many of its covers name an asset that exists nowhere in the project, as a count and never the names. Only a reader from whom nothing in the project is hidden is shown the count; for anyone else it is left out, which does not mean there are none. A cover reaches the asset of that name in every environment, including one you cannot see. The audit log records a change to a cover on the asset it was made on, and on no other. An owner or admin from whom nothing is hidden in any project they read is also shown the names of the covers that match nothing, and can remove one by naming it as an asset of any environment of its project.

You see the assets a domain covers that you are allowed to see. A domain’s counts are how many tables and views it reaches, through what it covers, and how many of those are certified. They count only what you may see, and nothing says how much is out of sight. An asset you cannot see is missing, not refused: naming one in a domain answers as if it did not exist.

A domain is archived and never deleted, and its slug is never used again. An archived domain stays in the list, marked, and keeps its assignments and what it covers. It takes no new assignment and no new asset, and it is left out when you choose a domain to assign. An owner or an admin can restore it.

Owners and stewards

An assignment names one person as the owner or the steward of one domain, layer, schema or table. A view is assigned as a table. The person must be a member of the organisation, and an assignment names a person, never a group. For each place and each role there is one person: assigning someone replaces the person named before, and choosing No one clears the assignment. A member who leaves the organisation loses their assignments, and the change is recorded.

An asset’s owner is its own, else its schema’s, else its layer’s. Its steward is worked out the same way and then falls back to the asset’s domain. The owner does not fall back to the domain. Every value names where it came from: set on the asset itself, or taken from its schema, its layer or its domain. The control plane works this out, and every screen shows its answer instead of working one out for itself.

An assignment names an asset by its project, its kind and its name, like a domain’s coverage does, so it holds in every environment of the project: naming a steward for a table in dev names one for the same table in prod. A name that only one environment declares is assigned there and nowhere else. An assignment, like a cover, reaches the asset of that name in every environment of the project, including one you cannot see. The audit log records a change to an assignment on the asset it was made on, and on no other. An owner or admin from whom nothing is hidden in any project they read can list the assignments on a layer, schema or table that no environment declares any more, and clear one.

Who may assign

Owners and admins change who owns, stewards or certifies. That is the stewardship.assign permission, and it is judged by role only. A domain is the organisation’s, so it is judged at the organisation. An assignment on an asset is judged by the role you hold in the asset’s project. Creating a domain, changing one, archiving one, assigning an owner or a steward and removing a certification are all under it.

A steward cannot assign. Being the steward of an asset gives that person nothing to say about who owns or stewards it.

Authority by assignment counts for a signed-in session and not for an API token. A token is created with less than the person who made it holds, so it is judged by its own role alone. A script that certifies a table with a token needs a role that may certify, and being the asset’s steward does not add to it. An agent cannot change anything on this page: every change here is refused for an agent.

Certification

A table or a view can be marked certified or deprecated. Nothing is chosen for you. A deprecated mark names the table or view to use instead, in the same environment, and a certified mark may not name one. You can add a note of up to 500 characters; a longer note is refused and never cut. The mark records who set it and when, and the record shows the note beside it. A mark set with an API token reads an API token and names no person, because a token certifies by its own role and never by an assignment.

The owners and admins of the asset’s project can certify it, and so can the asset’s owner or steward by assignment, whichever level the assignment came from. Only an owner or an admin can remove a mark. Someone who certified a table cannot take the mark off it unless they are an owner or an admin too. Removing a mark that is not there is not an error, so repeating the removal is safe.

A certified mark falls due after a year. It also falls due when the table is no longer the one that was certified: it was removed and declared again, or moved to another schema or name. A due mark reads Certification due on the record and in the list, and appears in the queue of the asset’s steward or owner, oldest first. A mark that fell due by age is dated by its due date. A mark that is due because the table was declared again or moved is dated by the last change to the table’s definition, so a later edit to the table moves its date. Certifying the asset again renews it, and a new mark replaces the old one. A deprecated mark does not fall due.

A certification also holds the table’s columns and its name. A change set that removes, renames or retypes a column the table declares in its own file waits for approval, whichever environment it is planned in, even one whose changes are normally committed at once. Deleting that file waits too, whether or not it declares a column, and so does changing the namespace or the name the file declares, because the plane then creates a different table and the one your consumers read is no longer the one the file declares. Moving the file to another path is a deletion of the old file, which waits, and a creation of the new one, which does not: the table at the new path starts with no certification of its own. Creating a table does not wait, and neither does creating it again under the name it had before; it is then the same table in a new life, so any mark it still carries reads Certification due and a later breaking change waits. Adding a column to the table’s own file does not wait. A column added inside a nested type reads as that column retyped, because a nested type is compared whole apart from its doc text, and a column renamed in a file that gives its columns no ids reads as removed. A commit pushed to your repository is not a change set, so no approval reason holds it: an environment that does not review projects it without an approval, and one that reviews holds what the branch brings until a person approves that transition.

A table counts while its mark reads Certified or Certification due; a deprecated mark holds nothing back. A table’s own file reaches every environment, so a change to it waits when the table is certified in any environment of the project. An environment’s own patch of the table waits when it changes the table’s schema, namespace or name in any way and the table is certified in that environment. An owner or an admin approves a change that waits, never the person who planned it unless nobody else can approve, and not the table’s steward as such. If the control plane cannot tell whether a table is certified, a change that adds, removes, renames or retypes a column, deletes the file or changes its namespace or name waits, and so does a file that cannot be read and an environment’s patch that changes the table’s schema, namespace or name; the reason says what the change is and that whether the table is certified could not be read. A change to nothing but the things the list at the end of this page names as not escalated still commits then.

The change set’s page gives the reason. For a table’s own file it counts the columns removed, renamed and retyped, or the columns a deletion takes, says when the change also moves the table, and names no column, no environment, and neither the old nor the new namespace or name; for an environment’s patch, and for a file that could not be read, it says so in its own words. The reason says that the table is certified and not in which environment, but anyone who is served the change set’s file can tell that some environment of the project certifies it, and the same reason is printed in the commit message or the pull request that your repository keeps, where it stays after the table is decertified. A draft shows the reason it was planned under, and whether the change waits is decided when it is submitted, on the marks as they are then. Under the diff, Impact says how many assets are downstream of each of the first five tables the change set holds, as you may see them. If Impact cannot be read, it says so in one sentence, and says that the change still waits for an approver only while the change set is proposed: a draft, a change set that has been approved and has its pull request open, and one that has ended say nothing of waiting. Certify and Remove certification name the kinds of change that wait, for a table and not for a view, and Remove certification says it only of a mark that is certified or due: removing the mark in one environment does not end it where the table is certified or due in another.

Where a table’s data comes from and what depends on it is on the Lineage page: its Impact lists each asset downstream of a table with its owner, its steward and whether it is certified.

The note is kept in the control plane as the text that was typed, and shown on the record. The audit log keeps a digest of it, never the words. The same goes for a domain’s name and description.

The Permissions page lists certification.set for owners and admins. That is the answer for the roles. It cannot show that a steward or owner by assignment may also certify what they are assigned, in a signed-in session, so a reader of that page alone would think an analyst who stewards a table cannot certify it.

Your queue

Your queue is what waits on you across the organisation. It holds two kinds of work. The first is a certified mark that has fallen due on an asset that you own or steward by assignment and may see. If you are an owner or an admin it is also every certified mark that has fallen due in a project where you may certify, whoever is assigned; a role that cannot certify puts nothing in it. At most fifty are listed, the oldest due first, and the queue says when more wait than are listed. The second is a term with a version waiting that you may approve or reject, in the Terms to approve section above the certifications. There a role does count: an owner or an admin sees every one, and a steward sees the terms of the domains they steward, in a signed-in session. Your own proposal is not in it, unless you are the organisation’s only member. When nothing of either kind waits on you, the queue reads Nothing waits on you. Glossary says who may decide a term.

Each item is a reference with the date it fell due, or for a term the date it was proposed, never text. A certification names its asset, its project and its environment; a term names the term, its version, its domain and the person who proposed it. The queue decides nothing: each item opens where it is decided, and an item in another project opens through a button that changes the scope only when you press it. An asset you cannot see is not in the queue and is not counted.

The control plane reads a bounded number of marks for each environment. When it stops before it has found them all, the section’s count reads not counted instead of a number, and the items are the ones it found.

No data access

Being a steward, or an owner by assignment, grants no access to data and no read of anything else. An assignment does not let you query a table you cannot query, see an asset you cannot see or read a column that a mask hides. Roles decide what a person may do in the control plane, and the Permissions page lists them. Who may read a row or a column is decided by the catalog’s policy, a separate system.

What a steward may and may not do

This is what an assignment gives a person who holds no role that gives it already.

From the command line

The rl command reads and does the same things. rl steward domain lists, creates, updates, archives and restores domains. rl steward assignment lists assignments and sets one, or clears it. rl steward queue prints your queue, and rl asset certify and rl asset decertify mark a table or a view and take the mark off, and rl glossary proposes, approves and exports terms. rl is judged by its API token’s own role, so a steward by assignment who is neither an owner nor an admin approves a term in the console and not with rl. Domains, assignments and the queue belong to the organisation, so those commands take no project or environment, except to say which environment an asset is in. The command-line reference lists each command, the permission it needs, how an idempotency key makes a retry the same change, and the exit codes.

What is not built

These are the things a steward might be expected to do that Stewardship does not do.

• A steward cannot review a description yet.
• When a change that removes, renames or retypes a column of a certified table merges, its certification does not fall due yet.
• A change to a top-level column’s required flag or defaults, to a column’s or a table’s doc, to a table’s labels, annotations, identifier fields, schema id, column order, partitions, properties, write order, routing format, routing engine or routing consumers, the adding of column ids to a file that had none or the dropping of them from one that had them, and the creation of a table, are not escalated for review yet.
• The reason a change set gives counts the columns a change removes, renames or retypes and does not name them yet.
• Your queue holds certifications that fell due by age and the terms waiting for your approval; descriptions to review are not in it yet.

Back to Governance