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.
About this guide
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.
Worked example
Build a business metric definition knowledge base
A fictional three-file metric exercise: decide whether C-104 counts, inspect the dashboard draft, and keep the refund rule open.
Try this task
Using only the three source files, define the weekly active-customer count, classify C-104, and review the dashboard draft. Preserve any unknowns and cite each conclusion with [[filename]].
Expected reasoning
Under revision 1, C-104 counts because the customer was paid and not canceled at the Tuesday action; the Thursday cancellation does not remove that week. The draft incorrectly filters at week end, and refund handling remains unknown.
Why keep this connected
A single metric contract can be checked in ordinary files. A source-linked metric wiki helps when definitions, exclusions, draft queries, and later revisions must remain inspectable together without pretending that a formula has been approved.
Review boundary
Check the action-time paid and not-canceled rule against C-104, compare it with the draft's week-end filter, and leave refund handling unknown for the metric owner.
Inspect the example in Wenlan
Wenlan v0.18.3 interface displaying data read back from an isolated test run. The sources are fictional and the reference answer was written for this exercise. No automatic AI generation or approval is shown.
After the cited source changed, Wenlan marked the page as out of date and kept its original text. The ‘updating…’ label indicates a pending rebuild here; it does not show a completed correction. Review the changed source before rebuilding and accepting a new answer.
Source files
Open a file to read its complete authored Markdown.
The source files are the same authored English dataset in all three locale views.
01weekly-active-customer-contract.mdWeekly active customer — revision 1
# Weekly active customer — revision 1 Owner: Growth Analytics Window: Monday 00:00 through Sunday 23:59 UTC. Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when cancellation is effective before the action timestamp; a cancellation after the action does not remove that week's activity. Exclude test accounts. The contract does not specify how refund state changes this metric. Leave refund handling unknown.
02qualifying-actions.mdQualifying customer actions
# Qualifying customer actions Count an event only when it has a customer_id and an event_at timestamp in UTC. The qualifying actions are: publish a reviewed knowledge page, complete a source review, or approve a revision for reuse. Do not count a login, a page view, a failed import, or an event without customer_id. The action list does not define revenue, retention, or customer health.
03dashboard-query-draft.mdExisting dashboard query — draft
# Existing dashboard query — draft Status: owner approval pending Window example: 2026-04-06 through 2026-04-12 UTC. The draft counts distinct customer_id values with a qualifying action and a paid subscription, then filters out any customer whose cancellation_date is before the end of the week. Example row: customer C-104 was paid and completed a qualifying action on Tuesday, then canceled on Thursday. The draft excludes C-104 because cancellation_date is inside the week. This query is a draft and is not an approved metric definition.
Reference answer
Reference answer: count the action-time state, then flag the draft query
Under revision 1, C-104 counts because the customer was paid and not canceled at the Tuesday action; a Thursday cancellation does not remove that week's activity. The draft query incorrectly excludes any cancellation before week end and still needs owner approval. Refund handling is unspecified.
Weekly active customer — reference
Definition
Count distinct customer_id values with at least one qualifying action in the Monday-through-Sunday UTC window. A qualifying action is publishing a reviewed knowledge page, completing a source review, or approving a revision for reuse. Login, page view, failed import, and events without customer_id do not count. weekly-active-customer-contract.md qualifying-actions.md
At the action timestamp, the subscription must be paid and not canceled. A customer whose cancellation becomes effective after the action still counts for this revision of the metric. weekly-active-customer-contract.md
C-104 and the draft query
C-104 counts in the example: the customer was paid and not canceled at the Tuesday qualifying action, while the Thursday cancellation happened afterward. The dashboard draft incorrectly removes C-104 by filtering cancellation_date at the end of the week. It is not an approved definition and needs the metric owner to reconcile its filter with the contract. weekly-active-customer-contract.md dashboard-query-draft.md
Refund handling is not specified by these sources. Keep it unknown rather than deciding whether a refund changes activity. weekly-active-customer-contract.md
Changed source: weekly-active-customer-contract.md
Expected update after this change
The revision changes the cancelled-but-paid case: C-104 no longer counts because the cancellation became effective on Thursday inside the measurement window, even though the qualifying action was on Tuesday. The reference must replace its action-time-only conclusion and the draft query's end-of-week exclusion is now consistent with this revised contract, subject to owner approval. Qualifying actions and unknown refund handling are unchanged.
# Weekly active customer — revision 2 Owner: Growth Analytics Window: Monday 00:00 through Sunday 23:59 UTC. Count distinct customer_id values with at least one qualifying action during the window. At the action timestamp, the subscription must be paid and not canceled. Exclude a customer when a cancellation becomes effective at any time during the window, even when the qualifying action happened before the cancellation. Exclude test accounts. The contract does not specify how refund state changes this metric. Leave refund handling unknown.
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