Data dictionary workflow
How to Build a Business Metric Definition Knowledge Base
Turn approved KPI specifications into a source-backed data dictionary with formula text, grain, exclusions, owners, revisions, and review state.
Article packet
Workflows
Data, analytics, product, finance, and operations teams resolving conflicting KPI definitions for people and AI agents
8 min read
01
Start with approved metric specifications, not dashboards or inferred formulas.
02
Keep formula text, grain, dimensions, exclusions, owner, and source revision in one record.
03
Supersede stale definitions explicitly instead of letting agents blend them together.
Inspect source revision and review state before trusting a metric
This genuine Wenlan desktop capture comes from the app's deterministic test fixture, not a company's analytics or finance workspace. It shows maintained Pages with source counts and a review queue, the same product surfaces used to keep conflicting or revised metric evidence visible.
- 01
Bound the approved specifications
Choose one metric family, allowed definition files, excluded systems, accountable owner, and named reviewer.
- 02
Distill one definition record
Keep definition, formula text, grain, dimensions, exclusions, citations, source revision, and conflicts in one reviewable Page.
- 03
Review before superseding
Open the cited source, inspect contradictions and stale state, then mark the current definition and retain the superseded revision.
Worked business metric record
This neutral template does not calculate a KPI. Replace every placeholder with approved specifications and a named domain reviewer.
- Meaning and formula text
- Business definition, non-executable formula, grain, dimensions, inclusions, exclusions, and edge cases.
- Owner and sources
- Accountable owner, exact source IDs and locations, source revisions, and effective dates.
- Review and supersession
- Current, stale, contradicted, or unresolved, plus the reviewer, superseded version, and next review trigger.
01
Quick answer
Create one reviewed record per business metric. Record the business definition, formula as non-executable text, grain, dimensions, exclusions, owner, exact source IDs and revisions, review state, and which older definition it supersedes. When two approved sources disagree, preserve the conflict until a named reviewer resolves it; do not let an AI agent invent one blended definition.
Wenlan can read approved Markdown, text, and text-extractable PDFs, maintain source-backed Pages, preserve citations and source revisions, run provenance lint, and leave an exact revision for human review. It does not ingest CSV or YAML, does not run SQL, does not connect to a warehouse or BI tool, does not compute metrics, does not provide lineage, does not monitor data quality, does not manage permissions, does not approve definitions, and does not automatically reconcile conflicts.
02
When this problem appears
A metric name such as active customer or net revenue can appear in a finance memo, analytics specification, product dashboard note, and operations handbook with different formulas, grains, exclusions, or owners. A polished summary can hide those differences. A useful data dictionary keeps each approved definition traceable, makes conflicts visible, and states which version is current without pretending to calculate the metric.
03
Build one approved-specification to metric-record loop
Begin with one metric family and a small set of approved definition files. The goal is a definition lookup and conflict-resolution record, not a live catalog of every table and dashboard.
- Name the metric, business question, accountable owner, included files, excluded sources, and reviewer before synthesis.
- Register approved Markdown, text, or text-extractable PDF specifications. Keep CSV, YAML, SQL, warehouse metadata, and dashboard APIs outside this workflow.
- Write the formula as reviewable text and record its grain, dimensions, time window, inclusions, exclusions, and known edge cases.
- Attach each important field to the exact source ID, heading or page, source revision, and effective date.
- When approved sources disagree, keep both definitions and mark the record contradicted or unresolved instead of averaging or merging them.
- After a reviewer selects a current definition, record which version it supersedes, retain the earlier revision, and set the next review trigger.
Wenlan workflow and a neutral metric-definition record
wenlan status
wenlan sources add ~/Metrics/approved-specifications
# In a Wenlan plugin client:
/distill <metric definition>
/pages <metric name>
/lint
/curate
metric: activated customer
business_definition: <what the approved sources mean>
formula_text: <non-executable formula from the approved spec>
grain: <account | workspace | user | event>
dimensions: <allowed breakdowns>
inclusions: <included states or events>
exclusions: <excluded states, events, or time windows>
owner: <accountable team or reviewer>
sources: <source IDs and exact locations>
source_revision: <version or effective date>
review_state: <current | stale | contradicted | unresolved>
supersedes: <previous definition or none>
next_review: <source-change trigger or date>04
What to check next
This workflow maintains reviewed definition records; it is not a data catalog, semantic layer, metric store, governance platform, or calculation engine. Wenlan does not ingest CSV, does not run SQL, does not connect to a warehouse or BI system, does not compute metrics, does not provide lineage, does not monitor data quality, does not manage permissions, does not approve definitions, and does not automatically reconcile conflicting formulas. A named domain owner remains responsible for the business decision.
Make one metric definition inspectable
Start with approved specification files, preserve conflicts and exact sources, and supersede an older definition only after a named reviewer checks it.
FAQ