Salesforce Requirements Document Template: New Fields (Free Download)

Most new-field requests arrive as a Slack message: “Can we add a Loss Reason field?” Then the questions start. What type? Which values? Required for everyone, or only at Closed Lost? Who can edit it? Does the data warehouse need it? This free Salesforce requirements document template puts those questions up front, so the admin can build the field once and the requester gets what they meant. Depending on where you work, you might call it a BRD, a PRD or a change request; it covers the same ground.

Why new fields need a written spec

A field looks like the smallest change you can make in Salesforce, but it’s one of the hardest to undo. Once a field holds data, changing its type can truncate or clear values, and some conversions aren’t allowed at all (see Salesforce’s considerations for converting field types). Other decisions are easy to forget until something breaks: help text, field-level security, whether integrations can still save records, and whether anyone plans to report on it.

A short spec makes those decisions visible before the build, gives reviewers something concrete to approve, and leaves a record of why the field exists. That record matters more every year, as descriptions and metadata increasingly feed reporting and AI tools (Salesforce Ben makes the case for a data dictionary).

What’s in the template

The template has 17 sections. Most of them apply to any Salesforce change; Section 8 is specific to new fields.

• Header, summary and scope: request ID, change type, impact type, the problem you’re solving, and what’s in and out of scope.
• Stakeholders and requirements: a RACI table and user stories with Given/When/Then acceptance criteria and MoSCoW priority (Trailhead has a good refresher on user stories).
• Technical specification (Section 8): the field-by-field detail an admin needs to build without guessing. More on this below.
• Impact analysis: why the change is worth doing and what it touches, plus a checklist written for new fields.
• Security, risks, stakeholder questions and a decision log: including 11 starter questions to ask before anyone opens Setup.
• Testing, deployment, enablement, post-launch results and sign-off: the parts that get skipped when a change feels “small”.

Guidance text is in gray italics, and each section is tagged [Required] or [Optional], so you can delete what doesn’t apply and share a clean document.

Section 8: the field specification

Section 8.1 is one table with a row per field: Object, Field Label, API Name, Description, Data Type, Field Details, Required? and Default Value. Writing out the API name (for example Loss_Reason__c) before the build lets report builders and integration owners plan around it. The Description is the admin-facing note on why the field exists and which request created it.

Section 8.2 is a cheat sheet covering every custom field type, from Text and Picklist to Roll-Up Summary, Formula and Geolocation. For each type it says what to decide and gives an example, so requesters know what to put in Field Details. A Picklist Values table follows, with the label, API name, field and controlling value for every option.

Section 8.3 is for formula fields: the formula itself, its return type, how it handles blank fields (treat blanks as zeroes or as blanks) and a few sample inputs with the expected result. Formulas are where admins most often build something slightly different from what was asked, and test values catch that early. Sections 8.4 and 8.5 cover where each field appears, what uses it, and related components such as validation rules, flows and permission sets.

“Required” isn’t one setting

The Required? column makes you choose one of five options, because “make it required” can mean very different things:

• Universal (set on the field): every save must include a value, including API updates, integrations and data loads.
• Page layout: required only for users editing through that layout in the UI.
• Dynamic Forms: required only on that Lightning page.
• Validation rule: required only under certain conditions, such as when Stage = Closed Lost.
• No.

Salesforce spells out how universally required fields behave, and Salesforce Ben has a useful decision guide for choosing between the options. Picking the wrong one either breaks an integration or leaves the field empty.

Showing the value of a new field

New fields usually create data that doesn’t exist yet, so there’s no baseline to improve on. The template’s impact section handles this with a “Capability & Visibility” impact type, framed as a chain: data captured → question answered → decision made → KPI improved later. You set leading indicators for the first 30–90 days (fill rate, the share of “Other” answers, dashboard usage, a retired spreadsheet) and name the KPI you’ll baseline once enough data exists. If the fields also replace manual work, there’s a time-savings calculator.

A worked example: Loss Reason Tracking

The example copy fills in every section for a fictional B2B SaaS company, Cedarloop Software. Its win rate had fallen from 27% to 22%, and 61% of closed-lost opportunities had no recorded reason. RevOps spent about three hours a week classifying losses by hand in a spreadsheet.

The request adds 15 Opportunity fields and 2 Account roll-ups, covering 14 data types:

• A Loss Reason picklist that controls a dependent Loss Sub-Reason
• A Primary Competitor lookup, filtered to competitor accounts
• Competitor product, number of competitors and the competitor’s quoted price
• A Price Gap % formula and a Days Open at Loss formula, each with test values
• Missing features (multi-select) and free-text loss details
• A closed-lost timestamp set by a flow
• Review fields: a checkbox, a revisit date and a call-recording link
• A decision-maker email, flagged as personal data
• Lost-opportunity count and amount roll-ups on Account

It also shows the supporting pieces a real request needs: two validation rules with a bypass permission, a flow, three permission sets, a dashboard, a partial backfill plan and a rollback plan. The impact section adds up to 228 hours a year of saved manual work, with leading indicators for adoption and a future KPI of win rate against the top three competitors.

How to use it

1. Make a copy and name it SF-REQ-### – New Fields – [Short Title].
2. Fill in the header, summary, scope and stakeholders with the requester.
3. Work through the stakeholder questions in Section 12. They cover most of the decisions Section 8 needs.
4. Complete Section 8: one row per field in 8.1, picklist values in 8.2, formulas in 8.3, placement in 8.4.
5. Pick the impact type(s) in Section 9 and complete the matching subsections.
6. Add test cases, get sign-off in Section 17, then build.

Salesforce limits worth knowing

A few platform limits come up often when you spec fields. Confirm them against current Salesforce Help, because limits change between releases.

• Field-level help text can be up to 510 characters (Salesforce Help).
• Formula fields can be up to 3,900 characters, and 15,000 bytes when compiled (formula limits).
• Restricted picklists allow 1,000 values in total, and multi-select picklists 500 (picklist limitations).
• Standard Field History Tracking covers 20 fields per object (field history tracking).

New to Salesforce data modeling? Trailhead’s Data Modeling module is a good place to start.

More templates are coming

This is the first in a series of Salesforce requirements templates built from the same master. Next up are new flows, field edits, flow updates, validation rules, page layouts, permissions, and reports and dashboards.