Data Dictionary
The Data Entities tab of a project's Dictionary pages: the things the project keeps records of, their fields, owners, personal data, retention and review status.
By the end of this page you will have written down what a project keeps records of, field by field, know every field an entity and a data field carry and what reads each one downstream, and know how an entity moves through its review and how it is removed.
A data entity is a thing the project keeps records of: a customer, an order, a branch, a shipment. Each carries its fields with their type, flags, validation and an example, the component whose records they are, the member who answers for it, whether it holds personal data and how long it is kept. Entities and fields are the data dictionary: requirements and business rules will name them, the API contracts and the database designs are read against them, and Heimdall reads them when it drafts stories, rules and test data.
The Data Entities tab is the second of the project's Dictionary pages; the first is the glossary, the words the project agrees on.
Before you begin
| You want to | You need |
|---|---|
| Open the Data Entities tab | data-entity:view-any on the project. Every staff role has it; a client guest has it through their project membership and sees the approved entities only. |
| Create an entity | data-entity:create, through your role on the project or your team role, or to own the team. Business analysts have it by default. |
| Edit or move an entity, or change its fields | data-entity:update. |
| Delete an entity | data-entity:delete. |
The page lives under a project: open the project, choose Dictionary in the sidebar and switch to Data Entities in the tab strip above the table.
Read the entities
The table lists one entity per row, in the project's order:
| Column | What it shows |
|---|---|
| Entity | The name with the plural beneath it, and a Personal data badge when the entity holds data about people. Press the name to open the detail flyout. |
| Component | The component whose records these are, or Whole project. |
| Owner | The team member who answers for the entity, or Unowned. |
| Fields | How many fields the entity carries. |
| Status | Where the entity stands in its review: draft, in review, approved or deprecated, as a coloured badge. Staff only. |
| Updated | How long ago the record last changed. |
| Row menu | View Entity, Edit Entity, Move to (the statuses the entity may move to), Activity, Delete Entity. |
Sort by entity, status or updated by pressing a column heading; press it again to flip the direction. Above the table, narrow the list with the search box (words in the name, the plural or the description), the status filter (staff only), the component filter and the Personal data switch, which shows the entities that hold personal data only. The filters travel in the page address; Clear Filters on the empty state drops them all.
A client guest sees the approved entities only, without the status column or the status filter.
Create an entity
- Press New Entity.
- Type the Name in the singular, unique within the project, and the Plural when it is not the name with an s.
- Pick the Component whose records these are, or leave it empty when the whole project shares them, and the Owner who answers for the entity.
- Write the Description: what the entity is and what it is for, in a sentence or two.
- Under Data Handling, switch on Personal data when the entity holds data about identifiable people, and write the Retention: how long records are kept and why.
- Under Fields, press Add Field once per field and fill each row: the Name, the Type, what it Points At for a reference, its Values for an enum, the Required, Unique and Personal data flags, an Example, the Validation rule in words and a Description. The arrows move a row up or down; the cross removes it.
- Press Create Entity.
The entity appears in the table at once as a draft; data_entity.created goes out to every
endpoint subscribed to it, followed by data_entity.fields_changed when the entity was created
with fields.
A name is all it needs
An entity can start as a bare name; the fields, the owner and the data handling follow as the analyst learns the domain, and Heimdall can draft the fields from the brief for review. Two rules hold from the start: the name is unique within the project, and no two fields of one entity share a name.
Open an entity
Press an entity's name, or View Entity in its row menu, to open the detail flyout: the status and personal-data badges, the name with its plural, component and owner, the description, the retention note, the Fields as a table (name and description, type with the entity a reference points at or the values of an enum, the flags, the example and the validation rule) and the created and updated stamps. From the flyout, Edit, Move to, Activity and Delete are one press away.
A link such as /projects/<project>/dictionary/entities?show=<id> opens the tab with that entity's
flyout already open; notifications and Heimdall's buttons use it.
Edit an entity and its fields
- Press Edit Entity in the row menu, or Edit in the flyout.
- Change what you need on the entity, and work the field rows: add, reorder, change or remove them. A new name must be free within the project.
- Press Save Changes.
A change to the entity itself travels as data_entity.updated with its old and new values; a
change to the rows travels as data_entity.fields_changed with how many fields were added,
changed and removed. An edit that changes nothing announces nothing. The status does not change
here; it moves from the list or the flyout.
Move an entity along its review
An entity starts as a draft. Put it in review when the people who approve it should read it,
mark it approved once they agree, and deprecate it when the project stops keeping those
records. Open Move to in the row menu or the flyout and choose the status; a deprecated entity
offers only the way back to draft. The move is written to the entity's history and travels as
data_entity.status_changed with the status before and after.
A client guest sees an entity while it is approved and not otherwise, so approving an entity is also what shares it with the client.
Delete an entity
Delete Entity in the row menu or Delete in the flyout removes the entity with its fields and its activity history after a confirmation; there is no undo. A reference field of another entity that pointed at it loses its target and keeps its name. Requirements and business rules that will name entities are not here yet; once they are, an entity they name will be deprecated rather than deleted.
All the fields
What happens next
- Every create, edit, move, change to the fields and delete is written to the entity's activity history with who did it and where from.
- The
data_entity.created,data_entity.updated,data_entity.status_changed,data_entity.fields_changedanddata_entity.deletedevents go out to every endpoint subscribed to them. - Requirements, business rules and the API contracts will name entities and fields as those modules land, which is why an entity in use is deprecated rather than deleted.
Heimdall on this page
Heimdall reads the dictionary through the same tools the MCP server offers and carries the open project as its context.
On the editor, Ask Heimdall beside each long field drafts it, improves it, shortens it, makes it testable or rewrites it as Given, When, Then; the draft waits under the field until you take it or drop it. See inline assists.
Writing the dictionary is a person's work, with Heimdall drafting for review: an agent over MCP reads the entities and their fields to design a table, a form or a payload, and never writes to them.
From the API and MCP
Data Entities API
List, get, create, change, move and delete entities and replace their fields over REST.
list_data_entities and get_data_entity
The two MCP tools that read a project's dictionary as the token sees it.
Permissions
| Action | Permission |
|---|---|
| See the entities | data-entity:view-any; a client guest sees the approved ones |
| Open an entity | data-entity:view |
| Create an entity | data-entity:create, or owning the team |
| Edit or move an entity, change its fields | data-entity:update, through a project role or a team role |
| Delete an entity | data-entity:delete |
| Read or restore its versions | data-entity:view to read, data-entity:update to restore; never a client guest |
Frequently asked
Related
- Traceability — the Links panel in the flyout: what this implements, verifies, depends on or relates to, read from either side
- Comments and mentions — the Discussion panel in the flyout: questions, answers, mentions, followers
- Attachments — the Files panel in the flyout: wireframes, specifications and samples pinned on the record
- Glossary — the words the project agrees on
- Components — the applications whose records the entities are
- The project overview — the project the dictionary belongs to
- Status reference — the review lifecycle
- Revisions and versions — every save kept, the fields with it, any version put back
data_entity.*webhook events
How is this guide?
Last updated on
Glossary
The Glossary tab of a project's Dictionary pages: the words the project agrees on, with definitions, other names, related terms and a review status.
Design References
The Designs page of a project: the links it keeps to Figma files, wireframes, prototypes, screenshots, API contracts and diagrams, attached to the whole project or to one component.