CRM field dictionary: document what your fields mean

Two CRM fields can have nearly identical labels and still answer different questions. One may be entered by a rep, another recalculated nightly, and a third copied from an enrichment provider. Looking at the label or latest modified date will not tell you which value should drive a handoff, report, workflow, or AI answer.

A CRM field dictionary records the business contract behind the field. It gives the people and systems using the data enough information to interpret it consistently. Start with the fields that carry important decisions. You do not need to document every administrative field before this becomes useful.

A field definition answers more than “what is this called?”

Platform descriptions often explain what a field stores. A useful business definition also explains why the value exists and how it may be used.

Dictionary entry	Question it answers
Object and field	Where does the value live?
Definition	What business fact or judgment does it represent?
Business question	Which specific question should this field answer?
Allowed values	What does each stored value mean?
Source	How did the value arrive?
Writer	Which person, integration, formula, or automation may change it?
Authority	May this value support the intended decision?
Primary source	Is this the original maintained value or a copy, rollup, or summary?
Freshness	When was the underlying fact checked, and when is it too old to use?
Write behavior	What happens when a person or system tries to change it?
Reporting use	Which reports include it, and what must those reports exclude?
Owner and review	Who approves its definition, and when is it reviewed?
Conflicts	Which similar fields or older definitions can be mistaken for it?

This dictionary becomes the field section of your Business Truth Map, the shared operating document for entities, lifecycles, stages, handoffs, fields, and unresolved questions. The CRM entity map defines the records first. The person and company relationship models live in the Lead and Contact lifecycle and Account lifecycle pages.

Source, authority, and freshness are different questions

These three ideas are often collapsed into one trust label.

Source describes how the value got there. Common sources include a person, a workflow, an integration, a formula, and an AI-generated assessment.

Authority describes whether the value can support a particular use. A manually entered value may be the approved source for a practitioner judgment. It may also be abandoned and stale. An automated value may be consistent while the job is healthy, but wrong when the input or rule is wrong. Source alone cannot settle the question.

Freshness describes whether the underlying fact is current enough for the decision. A nightly integration can update a record's generic modified timestamp without rechecking the fact you care about. Record the relevant observation or calculation time instead.

Example	Source	Authority for the stated use	Freshness rule
Contract end date from the billing system	Integration-written	Approved for renewal-window reporting when the account match is valid	Use the billing sync timestamp and flag a failed or overdue sync
CSM relationship assessment	Human-entered	Practitioner-owned input; compare it with other evidence without silently replacing it	Review on the agreed customer cadence
Account risk summary generated from activity	AI-generated	A lead to investigate, not proof of a completed action or commercial fact	Show the generation time and the source records reviewed
Days in current Opportunity stage	System-derived	Approved when it uses the documented stage-entry milestone	Recalculate from the event date; do not infer it from generic modification time

“Authoritative” is never permission to use a field for every purpose. State the decision or report the field supports. A contract end date may be authoritative for a renewal window and irrelevant to a person-consent decision.

Separate the business fact from the field that stores it

Begin with the question, then map the platform field. This keeps a Salesforce API name or HubSpot property from becoming the definition by accident.

For example, “When did Acme Manufacturing first become a customer?” is a business question. customer_since_at is one possible field. Its contract still needs to say:

which commercial event makes the relationship true;
whether the field records first entry, latest entry, or both;
which system writes it;
whether reactivation changes it;
how a migration preserves earlier history; and
which reports may use it.

The current Account lifecycle value answers where Acme is now. The milestone date answers when a defined event happened. A transition log can answer how Acme moved through several states. One field should not be forced to answer all three questions.

Document values as carefully as fields

A picklist label is not a definition. For every controlled value, record:

the plain-language meaning;
entry evidence or calculation rule;
what the value explicitly does not mean;
valid next values where sequence matters;
reporting treatment; and
replacement history when the value is retired.

This matters when a label sounds familiar. Qualified, Customer, Open, and Healthy can describe different facts on different records. Keep person lifecycle, Account lifecycle, Opportunity stage, work status, consent, employment, fit, ownership, and relationship health as separate dimensions even when their values appear in the same report.

Name the writer and the owner

The definition owner approves its meaning and use. The writer changes its value. Those responsibilities may belong to different people or systems.

Responsibility	What it controls
Definition owner	Meaning, intended use, and approved changes
Record owner	The person accountable for work on one CRM record
Writer	The user, integration, formula, workflow, or AI process that changes the value
Reporting owner	Population, joins, date logic, and exclusions in a report
Decision owner	The person who settles an unresolved business definition

Record write behavior too. A workflow may overwrite manual edits on every save. A formula may be readable but unavailable for a required aggregation. A copied field may lag behind its primary source. A successful API update does not prove the value will remain in place.

GTM Lab: resolve two fields that look current

The GTM Lab is a fictional B2B software company. Acme Manufacturing has two risk fields on its company record:

Entry	`account_health`	`renewal_risk_score`
Meaning	CSM's current relationship assessment	Nightly estimate of renewal risk from approved operating signals
Source	Human-entered	System-derived
Writer	Assigned CSM	Risk-scoring job
Authority	Practitioner-owned judgment; read and compare, do not overwrite silently	Approved for the worked risk-prioritization report while inputs are fresh
Freshness	Review at the documented customer cadence	Recalculated nightly; route an overdue run for review
Primary source	Primary source for the CSM's assessment	Primary source for the model's calculated score
Reporting use	Practitioner assessment and disagreement review	Worked risk band and prioritization report

The nightly job also touches Acme's record, so the record modified date is recent. That does not make the CSM assessment current. It only proves that something changed.

The two fields also do not need a universal winner. If the score is high while the CSM marks the relationship healthy, preserve both values and surface the disagreement. The worked rule routes the case to review with the sources and observation times. Silently copying one value over the other would destroy useful evidence.

This example is a design demonstration, not a universal risk model or freshness threshold.

Field dictionary template

Complete one entry for each field that changes a lifecycle, authorizes a handoff, defines a report population, carries a commercial milestone, or supplies important context to an automated decision.

Field	What to document
Stable ID	A durable identifier that survives a label change
Object and platform name	Record, display label, and API or internal name where useful
Definition	Plain-language fact or judgment represented
Business question	The one question this field is intended to answer
Allowed values	Stored values, reader-facing meanings, and retired replacements
Source and writer	How the value arrives and who or what may change it
Authority and intended use	Which decision or report it can support, including practitioner-owned judgment
Primary source	Whether it is original, copied, rolled up, summarized, or calculated
Evidence and lineage	Originating system, object, and field; association or rollup path; rule or workflow version; and supporting record or evidence link where appropriate
Freshness	Relevant observation time, update cadence, stale condition, and failure path
Write behavior	Manual, integration, formula, controlled automation, read-only, or generated behavior
Dependencies	Workflows, reports, calculations, integrations, and AI rules that read or write it
Reporting treatment	Included population, exclusions, joins, grouping limits, and event date
Governance	Definition owner, review cadence, known conflicts, and migration notes

Wrong choices that create false agreement

Wrong choice	What breaks	Better rule
Copy the field label into the dictionary as its definition	Teams keep their conflicting interpretations	Write the business question, meaning, and allowed-value rules in plain language
Trust whichever field changed most recently	Integration writes and unrelated edits impersonate freshness	Record the observation or calculation time that matters
Rank all human fields above automated fields, or the reverse	Source type becomes a shortcut for correctness	Define authority for the intended use and retain evidence
Call a rollup the source of truth	Readers cannot trace the value back to the maintained record	Name the primary source and the relationship path
Let AI overwrite a practitioner assessment	Human judgment and disagreement evidence disappear	Mark the field practitioner-owned and compare without silent replacement
Retire a field by renaming it `DNU`	Reports and workflows keep reading it without a migration path	Record its replacement, affected dependencies, owner, and retirement date
Document every field before prioritizing any	The project stalls while important fields remain ambiguous	Start with fields that change decisions, handoffs, automation, and reporting

Enrichment provenance

Enrichment adds a specific version of the source/authority/freshness problem this page already defines: a third-party provider becomes a source alongside your reps and your existing systems, and it writes at a moment your team doesn't control. Applying this page's vocabulary to that moment, rather than inventing a separate one, keeps enrichment from becoming a silent way to route around a field's existing authority rule.

Classify enrichment-touched fields the same way you'd classify any other field, with one addition specific to enrichment: whether the field is provider-sourced by default (nothing else reliably populates it, so the provider is the primary source until a human overrides it) or practitioner-owned-adjacent (a person's entry that enrichment should fill only when empty, never overwrite once populated).

Enrichment provenance category	Write behavior	Example
Provider-sourced by default	Refresh automatically on verified higher freshness	Company size, industry classification with no recent human override
Practitioner-owned-adjacent	Fill only if empty; never silently overwrite an existing value	A rep-entered job title, a CSM's account note
Empty field, any classification	Fill automatically	No existing value to conflict with

This is the same authority question this page already asks, applied specifically to the moment an enrichment job runs. It does not replace the general source, authority, freshness, and primary-source fields defined above; every enrichment-touched field still needs those. The operational rule for what happens when a provider's value disagrees with an existing one, including how the conflict gets logged and reviewed, is covered in full in conflict resolution and overwrite policy. Which records should be enriched at all, and at what moment, is a separate decision covered in enrichment eligibility and moment-of-use enrichment.

CRM field dictionary audit

Every load-bearing field has a plain-language meaning and one business question.
Controlled values have definitions, evidence, reporting treatment, and replacement history.
Source, writer, authority, primary-source status, and freshness are recorded separately.
Freshness uses a relevant observation or calculation time instead of generic record modification.
Person lifecycle, Account lifecycle, Opportunity stage, work status, consent, employment, fit, ownership, and relationship health remain separate.
Practitioner-owned judgments can be compared without silent overwrite.
Copied, rolled-up, calculated, and AI-generated fields point to their originating fields, relationship path, calculation or workflow version, and supporting evidence.
Reports and automations that depend on the field are visible before its definition changes.
Known conflicts, retired fields, migration notes, owners, and review dates are recorded.

The business dictionary should exist before an AI-specific rules layer. Once the meaning is approved, the CRM AI context overview shows how to deliver it to an agent, and the context-layer rule schema's field entries add runtime fields such as scope, write policy, and tests. The same definition can support people, workflows, reporting, and AI without asking each system to guess what the CRM meant. For generated summaries and assessments, use the additional provenance and confirmation controls in AI-generated CRM fields.