Meaning and personal data
Declare what a dataset means, keep its history, document its columns, and control how personal data leaves Möbius.
A steward does two jobs before a dataset is trusted: says what it means, and says which of its columns are personal. This guide covers both. For how the meaning is then checked, see Certification and gates; for what each step records, see the audit trail.
Write the semantic contract
Every dataset carries one semantic contract. It records:
- Grain — what one row is, in words ("One row = one customer per month"), plus an optional structured grain: a type (One per entity, Aggregate, Snapshot, Event stream, Unkeyed append) and the ordered key columns.
- Meaning — one or two sentences on what the dataset is.
- Steward — the one person who certifies the dataset. It must be a member with the Steward role or above, and a workspace admin assigns or changes it.
- Owner — the person who registered the dataset. Shown as OWNER on the dataset's Access page.
- Decision boundaries — where the data may be used: API access, Webhooks, Exports, AI, ML workflows, Dashboards.
- Intent and allowed consumers — the decision class (METRIC, DECISION, OPERATIONAL, EXPLORATORY) and which kinds of consumer may read it (HUMAN, AI, AUTOMATION, EXTERNAL).
- Sources and constraints — optional JSON.
In the dashboard. Open the dataset, go to Settings → Governance and use the button on the Semantic Contract card. It opens Governance Review, where you fill in grain, meaning and decision boundaries, then Save Draft or Mark contract In Review. You need the Editor workspace role or above and write access to the dataset. The steward picker on the same page is for workspace admins.
From the CLI. mb contract set-intent sets intent, allowed consumers and the structured
grain. It keeps the existing grain and meaning unless you pass new ones:
mb contract set-intent <tableId> --intent DECISION --allowed-consumers HUMAN,AI
# First contract on a dataset: pass grain and meaning too
mb contract set-intent <tableId> --intent METRIC \
--grain "One row per order line" --meaning "Every order line booked in the shop." \
--grain-type ONE_PER_ENTITY --grain-key order_id,line_no| Flag | What it does |
|---|---|
--intent <type> | Decision class, or none to clear |
--allowed-consumers <list> | Comma-separated consumer kinds, or none for unrestricted |
--grain <text> / --meaning <text> | Replace the grain or meaning text |
--grain-type <type> | Structured grain type, or none to clear it |
--grain-key <columns> | Ordered key columns (needs --grain-type) |
--grain-not-expressible | The grain can't be written as columns; shown as "grain: NOT machine-verified" |
--grain-surrogate-only | The key is a system row id, not a business key |
--json | Machine-readable output |
See the CLI reference for every mb contract option.
The Workspace API equivalent is GET / PUT /api/tables/{id}/semantic-contract. A PUT
replaces grain and meaning, so send them on every call.
Changing the contract of a certified dataset
Editing the contract of a dataset that is already certified does not change what is certified. Your edit is saved as a draft in review, the card shows Draft pending re-certification, and the approved contract stays in force until the draft is reviewed in Governance Review and certified. Certification itself is covered in Certification and gates.
Restore an earlier contract
Möbius keeps a version of the contract each time the dataset is certified.
- Dashboard: Settings → Governance → Contract version history. Each version shows who certified it and when; Restore asks for a reason.
- CLI:
mb versions list <tableId>
mb versions restore <tableId> --to v3 --reason "v4 widened the grain by mistake"See the CLI reference for every mb versions option.
A restore copies the old content onto the live contract as a new version. Nothing is deleted,
and the new version records which version it came from. Restoring does not certify anything:
if the dataset is certified, a recertification request is filed and the current certification
stands until a steward recertifies. Restores stay in one environment; --env <label> checks
you are in the one you expect and refuses on a mismatch. You need the Steward role or above.
A rejected or deprecated contract can't be restored, and neither can the latest version.
Seed a contract from dbt
If a dataset is already modelled in dbt, import its schema.yml entry as a starting draft:
| dbt | Becomes |
|---|---|
| Model description | Contract meaning |
| Column description | Data dictionary description |
unique | Grain ("One row per …") |
not_null | Required field |
relationships | Field reference |
accepted_values | Declared allowed values (not yet an enforced check) |
data_type | Field type |
| Any other test | Kept for the steward to review, never enforced |
Both tests: and data_tests: are read. The import:
- only writes to a dataset that has no contract or a draft one. A contract in review or certified is never overwritten.
- never overwrites a value a person has edited since the last import, so you can re-run it.
- never submits or certifies anything.
Send it to the Workspace API with a service token that has the Author definitions scope (minted in Settings → Integrations; the scope needs the Steward role or above):
curl -X POST https://<your-host>/api/workspace/contract-seed \
-H "Authorization: Bearer $MOBIUS_TOKEN" -H "Content-Type: application/json" \
-d '{"tableName": "orders", "model": "orders", "schemaYaml": "<contents of schema.yml>"}'model is needed only when the file declares more than one model. The same import is
available as a Workspace MCP tool. There is no mb command for it.
Document columns in the data dictionary
Open the dataset and choose Data Dictionary. Each column has a description, examples, synonyms, an owner, notes, a PII class and a mask strategy. Editing needs write access to the dataset; everyone who can read the dataset can view it. The dictionary is a tenant capability control (Data Dictionary AI); if it is off, ask your workspace admin.
Generate descriptions. Ask the in-app assistant (the Chat button on the dataset, or Send to chat on a column), or your own AI tool over Workspace MCP, to suggest dictionary edits or to fill an empty dictionary. Suggestions are drawn from a sample of the data.
Set how samples are taken. Workspace → Workspace Profile → Data Dictionary Settings applies to the whole workspace:
- Sampling strategy — Head + Tail, Reservoir, or Stratified (categorical).
- Sample limit — 100 to 5,000 rows (default 1,500).
- Anonymize obvious PII in samples — on or off.
Accept or reject proposed changes. Suggested edits never overwrite the dictionary directly. They arrive as a proposal: approve the changes you want (one by one) or reject the proposal. Either answer is recorded, and both need the Editor role or above.
Generate a schema card
A schema card is a short generated summary of a dataset: its columns, their types and profiles, and what the data looks like, for a person or an AI to read before using it. On the dataset's Data View, open Schema Actions → Create Schema Card (later Update Schema Card). You need write access, and the dataset must be pending review, certified or deprecated. The assistant and Workspace MCP read the card through the same tool, which returns aggregates only, never rows.
Declare what happened to changed columns
When a certified dataset's columns change, a column diff can't tell a rename from a drop and an add. In Governance Review, the Review changes since last certification panel lets a steward declare it:
- Detected changes — confirm each change Möbius found.
- Column changes needing intent — for a column that is gone, choose Renamed to another column, Removed (tombstoned) with a reason, or Replaced by another column with a note. New columns are recorded as additive.
Select Submit declarations. You need the Steward role or above. Declaring is optional and never blocks certifying or rejecting. The declarations are kept with the contract version that certifies them.
Classify personal data
Every column has a PII Class: none, personal or sensitive. A column you haven't classified yet is undeclared, which is not the same as none.
Detection. When a dataset is created, Möbius checks its column names for patterns that look like personal data (email, phone, address, date of birth and similar). It reads names, not values. Each match is an open suggestion in your notifications, linking to that column in the Data Dictionary. A suggestion never classifies anything for you. You can re-run detection on an existing dataset through the assistant or Workspace MCP.
Classify. On the Data Dictionary, set the column's PII Class and Mask Strategy. Review this column opens the assistant to explain the flag. Through the assistant you can also dismiss a suggestion with a reason, which leaves the column undeclared. Classifying needs the Editor role or above.
Before certifying. A dataset can't certify cleanly while any column whose name looks personal is undeclared. Mark each one personal, sensitive or none. "None" means you reviewed it and it is served as-is.
Choose how personal data is masked
Columns classed personal or sensitive are masked at the moment they are read, using the column's Mask Strategy:
| Strategy | What the reader gets |
|---|---|
| redact | [REDACTED] |
| hash | A 16-character keyed hash, the same for the same value within your workspace (so you can still join on it) and different across workspaces |
| partial | The last four characters, the rest as •. Values of four characters or fewer are fully masked. Non-text values are redacted |
| none | Treated as redact: personal data is never served raw because a strategy is missing |
An empty value stays empty. Masking applies to datasets held in place and held by Möbius alike, on the Data API, Data MCP, outbound webhooks, decision views and the in-app assistant's answers. It also applies to every file that leaves Möbius: Export CSV and exports to your S3 bucket, always. The app's own screens show rows as stored to anyone who can read the dataset, and so does the certified view Möbius publishes in your own warehouse, where your warehouse's controls apply. See How Möbius masks personal data.
Grant unmasked access to a service token
When a system really needs the raw value, give its Data API token a column-level unmask grant rather than reclassifying the column.
- In Settings → Integrations, create the token and select its datasets.
- Under PII unmask grants, tick the personal or sensitive columns it may receive unmasked.
- To remove one later, find the token in the list and select Revoke next to the grant. The next read is masked again.
Only a workspace Admin or Owner who also administers the dataset can grant. Grants apply only to columns classed personal or sensitive, and only in the token's own environment. Creating a grant, revoking it, and each query that returns unmasked values (once per query, not per row) are all recorded in the audit trail. A grant has no end date of its own: it lasts until you revoke it or the token is revoked.
Control who can read and write a dataset
Open the dataset's Settings → Access. Under User Permissions, enter a member's email and choose Read, Write or Admin. Remove access with the bin icon. The dataset's owner always has access.
- Workspace Stewards, Admins and Owners can read every dataset. Admins and Owners administer every dataset.
- The workspace role caps what a dataset grant can do. A Viewer given Write still can't write.
- A banner shows your workspace's access-control setting. When it says Enforced, Editors need an explicit grant to write.
- Bulk grant (for dataset admins) gives one member the same permission across every dataset in the workspace or across a data group. Workspace Admins can do the same from Workspace → Table Access.
Granting and changing access needs Admin on the dataset (its owner, an Admin grant, or the workspace Admin or Owner role). Every grant is recorded.