Quick answer: A CRM data dictionary is a short agreement about what each field means, where it belongs, who updates it and which values are allowed. Build it before a migration or automation. Otherwise a tidy import can create three versions of “lead source” and nobody knows which one pays the bills.
Jump to: Minimum dictionary · Worked example · Migration test · Copyable record
For: small service businesses, founders and lean teams setting up or cleaning a CRM. This is a vendor-neutral operating guide. Product capabilities should be checked in the selected account and plan. Examples are hypothetical; no customer results are claimed.
Decision gate: If two colleagues interpret a field differently, do not automate it yet.
- What a CRM data dictionary actually does
- Choose the object before naming the field
- The minimum useful dictionary
- Worked example: seven fields for a service enquiry
- Treat lead source as several defined facts
- Choose field types that prevent avoidable cleanup
- Make required fields earn the interruption
- Map and test before the full migration
- Keep the dictionary alive without creating bureaucracy
- Five acceptance tests
- Copyable CRM field record
- Useful detail: Save the internal field name in the dictionary
- Sources and editorial basis
What a CRM data dictionary actually does
A data dictionary is not a grand database project. For a small team, it can be one maintained table with a row for every field the team relies on. The row explains the field’s business meaning, record type, format, allowed values, owner and source. It also says whether the field is required and what happens when the answer is unknown.
The point is not prettier documentation. The point is consistent action. If “Customer type” means industry to one person, contract tier to another and “good prospect” to a third, filters and reports will disagree even when every cell is filled.
HubSpot’s official documentation describes properties as fields that store information on CRM records and documents how administrators can create and edit them. Its import documentation describes mapping spreadsheet columns to CRM properties. Those product mechanics make the operating definition more important, not less: the system can store a value without understanding what your team meant.
Choose the object before naming the field
Start by deciding what the value describes. A person’s email belongs on a contact. A company’s industry belongs on a company. A proposal amount, stage and expected close date normally describe a deal or opportunity. A call outcome describes an activity. Exact object names vary by product, but the boundary should be written before import.
A common failure is putting a job-level status on the contact. One customer can request a website review and maintenance at the same time. If the contact has only one “Stage” field, closing the review can accidentally make the maintenance request look finished. Keep the relationship and the separate pieces of work connected rather than squeezing both into one label. See the shared inbox versus CRM guide for a worked two-job example.
The minimum useful dictionary
On a small screen, swipe the table sideways to see all columns.
| Dictionary column | Question it answers | Example |
|---|---|---|
| Field label | What will users see? | Next action due date |
| Object | What does the value describe? | Deal / enquiry |
| Plain-English definition | What exactly counts? | Date the named owner must take the next recorded action |
| Type and allowed values | What can be entered? | Date; blank only when closed |
| Owner / source | Who or what updates it? | Deal owner after each customer interaction |
| Used by | Which view, report or automation depends on it? | Daily overdue queue |
| Unknown rule | What happens when the answer is missing? | Leave blank and route to review; do not guess |
Keep the first version short. Document the fields used to route work, contact a customer, define the pipeline and produce the measures the team actually reviews. A field that has no owner or consumer is a candidate to postpone.
Worked example: seven fields for a service enquiry
Suppose a fictional three-person agency receives website enquiries. Its first dictionary could define:
- Enquiry reference: unique internal identifier for this piece of work; created by the CRM or intake process.
- Contact: the person linked to the enquiry; not a substitute for a separate company or deal record.
- Service requested: controlled list such as audit, new site, maintenance or other.
- Owner: named person responsible for the next action; never the word “sales”.
- Stage: evidence-based status using the team’s written exit criteria.
- Next action: specific verb plus outcome, such as “Jordan sends the page list”.
- Next action due: date or time the owner must act; blank only under a documented closed state.
Those definitions make the lead follow-up process testable. They also keep the pipeline measures tied to the same stage and ownership rules. Adding thirty optional fields before these seven work reliably is decoration with a login screen.
Treat lead source as several defined facts
“Lead source” often hides different events. Define separate fields for the earliest supported discovery source, the latest supported return source, the CRM record-creation method and raw campaign detail. Add a self-reported source only when it is clearly labelled as the customer’s answer rather than measured history.
- Original source: preserve the earliest supported value and its date.
- Latest source: update under a written rule without overwriting the original.
- Record source: form, import, integration, API or manual creation.
- Campaign detail: raw source, medium, campaign and content values when captured.
- Evidence status: system observed, customer reported, manually verified or unknown.
Use the CRM lead-source tracking guide for the full field set, worked example and reporting rules. If the CRM automatically maintains a property, document its behaviour before allowing manual edits.
Choose field types that prevent avoidable cleanup
Use a controlled choice when the team must group values consistently. Use free text when nuance matters and nobody needs exact grouping. Use a date for a real date, not a text field containing “next week”. Use a checkbox only when the meaning of checked and unchecked is explicit; unchecked can mean “no”, “not yet reviewed” or “not applicable”, and those are different states.
Do not use a dropdown to hide uncertainty. If staff routinely choose “Other”, decide whether the list is incomplete or the field should remain free text. If a value is unknown, preserve unknown rather than filling a plausible guess. Clean-looking fiction is worse than an honest blank.
Make required fields earn the interruption
A required field should block bad work, not merely make a report look complete. Ask three questions before making one mandatory:
- Can the user know the answer at this point in the workflow?
- Will a specific action, view or report use it?
- Is there a safe value for unknown, or should the record move to a review queue?
For example, making “Lost reason” required when an enquiry is closed can improve review quality. Making it required when the enquiry first arrives forces guessing. Apply the rule at the point where the information becomes knowable.
Map and test before the full migration
HubSpot’s official import guidance describes mapping file columns to CRM properties and using identifiers when records should be updated rather than created again. Treat the mapping as a controlled change:
- Copy each source column into a mapping sheet.
- Choose the target object and target field from the dictionary.
- Mark transform rules, such as “Web design” and “Website” becoming one allowed value.
- Identify the unique key used to update an existing record.
- Import a permitted sample, then compare counts, blanks, duplicates, relationships and dates.
Do not create a new custom field just because an import column fails to match automatically. First check whether an existing property has the intended meaning. A near-duplicate field name can turn one source of truth into two polite suggestions.
Use the CRM migration checklist for cutover steps and the duplicate cleanup guide when the sample reveals competing records.
Keep the dictionary alive without creating bureaucracy
Name one dictionary owner and one backup. A field change should record the date, reason, affected imports, forms, views, reports and automations. Review unused or confusing fields on a simple cadence, such as after a migration and then quarterly. That cadence is a suggested starting point, not a universal requirement.
Before renaming, changing a field type or removing an allowed value, test downstream uses. A friendly label can feed a less friendly integration. Preserve an export or documented rollback route before a material bulk update. This guide does not authorise deleting fields or customer data.
Five acceptance tests
- New enquiry: two colleagues choose the same object and stage from the same facts.
- Unknown value: the user can follow the documented blank or review rule without guessing.
- Second job: one customer can have two open pieces of work without overwriting either status.
- Import update: a sample update changes the intended record and does not create a duplicate.
- Report trace: every number in the weekly review points back to the field definition and its denominator.
Record pass, fail and not tested separately. If the test needs administrator access or manual correction that ordinary users will not have, it has not proved the daily workflow.
Copyable CRM field record
Field label:
Internal name, if relevant:
Object / record type:
Plain-English definition:
Field type and allowed values:
Required at which stage:
Unknown / not-applicable rule:
Source and update owner:
Views, reports, imports and automations using it:
Example valid value:
Example invalid or ambiguous value:
Last reviewed date and reviewer:
Decision rule: keep the field if it changes a real action, preserves necessary context or supports a reviewed measure. Combine or retire it only after checking dependencies and preserving required data. Add a new field when the team can explain why an existing field cannot carry the meaning safely.
Useful detail: Save the internal field name in the dictionary
HubSpot property labels can change, but a property’s internal name cannot be edited after creation.
Keep both names in the data dictionary. The label helps a colleague fill in the field; the internal name helps an implementer identify what an integration actually writes.
Try this:
- Add label, internal name, object and allowed values to the field record.
- Have a colleague identify the field using that record.
- Before renaming a label, inspect the connected mapping instead of creating a second almost-identical property.
Source: HubSpot: property editor and internal names. Checked October 3, 2026. The practical check is a PSL suggestion.
Sources and editorial basis
Primary product references checked September 30, 2026: HubSpot’s create and edit properties, import tool overview, import-file requirements and record association guidance. Product screens, permissions and plan availability can change; verify them in the intended account before implementation.
The dictionary structure, examples, acceptance tests and governance rules are Practical SaaS Lab editorial proposals, not measured customer results or a hands-on product comparison.
