Reference Data

Some of what a project needs to document is not prose but small structured facts: a status enum with its associated colors, a CDE folder structure, the set of metadata fields required per file. Reference data is how dotBEP stores that kind of information: structured, organized into named domains, and defined once at the BEP level instead of being duplicated inside any single document.

Think of the relationship between reference data and standards this way: a standard is the narrative, written for people, that explains a rule or a requirement. Reference data is the structured version of the specific values behind that narrative, written to be read with certainty by whatever consumes it, a script, an integration, another part of the BEP, without needing to parse prose to guess at them.

Two ways to use reference data

Configuring external systems

The primary use case for reference data is external consumption. An integration, a script, or any tool connected to your project can read a reference data domain and get back the exact current values it needs, a set of allowed status values, a folder structure, a list of required fields, with certainty.

Create a reference data domain called "CDE" for our Common Data Environment conventions, with the folder structure and the metadata fields required per file.

Referencing it from a standard

Reference data can also be referenced directly from a standard’s prose, so the standard always shows the current values instead of a copy that can silently drift out of sync. See Standards and Guides for how to reference reference data, or embed a live table of it, from within a standard.

Domains and nodes

A domain groups related data under a name, for example “Topics” for how coordination issues are classified, or “CDE” for your Common Data Environment conventions. Within a domain, each entry is a node: a small piece of structured data that can hold its own attributes and, optionally, children, so you can represent both flat lists (a set of status values) and hierarchies (a folder structure).

Add a "Topics" reference data domain with a "Status" group containing "Open", "In progress", and "Resolved", each with a label and a color.

In the "CDE" domain, add a "Folders" group with "WIP" containing "Structural", "MEP", and "Architecture" as subfolders, and "Shared", "Published", and "Archive" as top-level folders.

Key and label

Every node has both a key and a label, and the two serve different purposes.

The key is the technical identifier: it is what other software reads to work with the node reliably, and it does not need to be human-friendly. The label is required, and is what should actually be shown to a person reading the domain.

If a specific technical key matters, for example because an existing integration already expects a particular value, say so explicitly. Otherwise, describe the values you want in plain language and let the AI choose a sensible key.

Group data of the same shape together

When defining a domain, keep data that shares the same shape under its own node, rather than mixing unrelated kinds of data at the same level. A CDE domain, for instance, is clearer as two separate groups, one for the folder structure and one for the required file metadata fields, than as a single flat list mixing both. This keeps each part of the domain predictable for whatever reads it, whether that is a person, an external system, or a table embedded in a standard.

Referencing other BEP data

A node’s attributes can point directly at other data in the BEP instead of repeating it as plain text, the same way a standard can. If a folder in your CDE domain is owned by a specific team, reference that team’s name rather than writing it out:

In the "CDE" domain, set the owner of the "Structural" folder under "WIP" to the [team name] team, referenced by name.

If the team is renamed later, the reference updates with it automatically, and dotBEP will not let you delete a team, member, or other entity that reference data still depends on.