Functional Specification Document (FSD) Template

Roles and permissions matrix, per-feature flows, business rules, validation, messages, data fields, reports, notifications

Requisitos y análisisCompletafunctional specificationActualizada 20 oct 2026

Abrir en el editorDescargar .md

Cómo usar: Use it when developers and testers need exact product behaviour per feature before building. Fill the roles, permissions matrix and feature list first, then copy the feature block for each feature. The main pitfall is vague validation rules and error messages.

Vista previa

Functional Specification: [Product or feature name]

Complete functional specification document (FSD). It describes exactly how the product behaves from the user's point of view: roles and permissions, each feature's flows, business rules, screens, validation, messages and data. Based on common industry practice for functional specifications. Replace every [bracketed] value and every row marked Example.

Document control

Field	Value
Document ID	[FSD-PRODUCT-001]
Product / feature	[Name] [release]
Version	[0.1]
Status	[Draft / In review / Approved / Superseded]
Author	[@business-analyst]
Product owner	[@product-owner]
Classification	[Internal / Confidential]
Last updated	YYYY-MM-DD
Related documents	[BRS / PRD], [SRS], [UX designs], [Technical design], [Test plan]

Approvals

Role	Name	Decision	Date
Product owner	[@name]	[Approved / Rejected / Approved with comments]	YYYY-MM-DD
Engineering lead	[@name]	[Decision]	YYYY-MM-DD
QA lead	[@name]	[Decision]	YYYY-MM-DD
UX lead	[@name]	[Decision]	YYYY-MM-DD

Revision history

Version	Date	Author	Change summary
0.1	YYYY-MM-DD	[@name]	First draft of features F-01 to F-03
0.2	YYYY-MM-DD	[@name]	Example: Added refund approval rule BR-07; updated error messages after UX review
1.0	YYYY-MM-DD	[@name]	Example: Approved for development of release 2

Introduction
User roles and permissions
Functional overview
Global rules and conventions
Feature specifications
Reporting
Notifications
Integrations
Non-functional summary
Acceptance criteria summary
Open issues and decisions
Appendices

1. Introduction

1.1 Purpose

This document specifies the functional behaviour of [Product name] [release]. It is the reference for design, development, testing, documentation and user acceptance.

1.2 Scope

In scope: [feature F-01], [feature F-02], [feature F-03].
Out of scope: [feature excluded], [feature in a later release].
Assumptions: [assumption that affects behaviour, for example "users are already signed in through single sign-on"].

1.3 Audience and how to read

[Who reads which sections. Example: developers and testers read 4 and 5; operations reads 7 and 8; sponsors read 1, 3 and 10.]

1.4 Source requirements

Source	ID range	Location
Example: Business requirements	BR-001 to BR-012	BRS 1.0
Example: User stories	ORD-101 to ORD-140	Backlog
[Source]	[IDs]	[Location]

2. User roles and permissions

2.1 Roles

Role	Description	Typical users	Number
Example: Customer	Places and tracks orders	Registered shoppers	50,000
Example: Support agent	Handles order queries and refunds up to a limit	Contact centre staff	40
Example: Support supervisor	Approves refunds above the agent limit	Team leads	6
Example: Administrator	Configures products, prices and roles	Operations	3
[Role]	[Description]	[Users]	[n]

2.2 Permissions matrix

C = create, R = read, U = update, D = delete, A = approve, dash = no access.

Function	Customer	Support agent	Support supervisor	Administrator
Orders (own)	C R U	R	R	R
Orders (all)	-	R U	R U	R
Refunds up to [limit]	-	C	C A	-
Refunds above [limit]	-	C	A	-
Product catalogue	R	R	R	C R U D
User roles	-	-	-	C R U D
Reports	-	R (own team)	R	R

3. Functional overview

[Short narrative of what the product does and the main user journeys.]

The feature map below shows how the main features relate.

ID	Feature	Primary role	Priority	Source
F-01	Example: Browse and search	Customer	Must	BR-001
F-02	Example: Cart and checkout	Customer	Must	BR-002
F-03	Example: Order tracking	Customer, agent	Must	BR-004
F-04	Example: Returns and refunds	Customer, agent, supervisor	Should	BR-007
F-05	[Feature]	[Role]	[MoSCoW]	[Source]

4. Global rules and conventions

Dates and times: shown in the user's time zone as [YYYY-MM-DD HH:mm]; stored in UTC.
Currency: [ISO 4217 code], two decimal places, rounding half-up.
Required fields: marked with an asterisk and announced to screen readers.
Validation timing: on leaving the field and again on submit.
Error message style: say what is wrong and how to fix it, in plain language, next to the field. No error codes in user-facing text.
Audit: every create, update and delete stores user, time and old and new values.
Accessibility: [WCAG 2.2 level AA].
Languages: [list]; all user-facing text comes from translation files.

5. Feature specifications

5.1 F-04 Returns and refunds

5.1.1 Description

Example: Lets a customer request a return for delivered items within the return window, and lets support staff approve and refund it. Supports full and partial refunds to the original payment method.

5.1.2 Actors and preconditions

Actors: Customer, Support agent, Support supervisor.
Preconditions: The order exists, has status Delivered, and the delivery date is within [30] days.
Trigger: Customer selects "Return items" on an order, or an agent opens a return on the customer's behalf.

5.1.3 Main flow

Customer opens a delivered order and selects "Return items".
System lists the returnable items with quantity selectors.
Customer selects items and quantities and chooses a reason.
System validates the request (5.1.6) and shows the refund amount.
Customer confirms.
System creates a return with status Requested, emails a return label and shows the return number.
Warehouse scans the returned parcel; system sets status Received.
Support agent inspects and selects "Approve refund".
System refunds to the original payment method and sets status Refunded.
System notifies the customer (N-03).

5.1.4 Alternate and exception flows

ID	At step	Condition	Behaviour
A1	2	Some items are not returnable (final sale)	Items shown greyed with reason "Final sale items cannot be returned"
A2	4	Return window has passed	Request blocked; message E-RET-02; link to contact support
A3	8	Refund above agent limit	Status Awaiting approval; supervisor notified (N-04)
A4	9	Payment provider declines refund	Status Refund failed; agent alerted; retry or store credit offered
A5	8	Item damaged by customer	Agent selects "Reject" with reason; customer notified (N-05)

5.1.5 Business rules

ID	Rule
BR-RET-01	Example: Returns are accepted up to 30 days after delivery date.
BR-RET-02	Example: Original shipping is refunded only when the whole order is returned.
BR-RET-03	Example: Agents may approve refunds up to 200; above that a supervisor must approve.
BR-RET-04	Example: One open return per order line at a time.

5.1.6 Validation rules

Field	Rule	Error message ID
Quantity	Integer, 1 to quantity delivered minus quantity already returned	E-RET-01
Reason	Required; one of the configured reasons	E-RET-03
Comment	Optional; up to 500 characters	E-RET-04
Delivery date	Within 30 days of today	E-RET-02

5.1.7 User interface elements

Element	Type	Behaviour
Return items	Button	Visible only for Delivered orders inside the window
Item quantity	Number stepper	Range from validation rules
Return reason	Select	Values from configuration table RET_REASON
Refund summary	Read-only panel	Updates as items are selected
Confirm return	Primary button	Disabled until at least one item and a reason are chosen

Wireframe or design reference: [link to design file, frame name].

5.1.8 Error and information messages

ID	Text shown to the user	Shown when
E-RET-01	"Choose a quantity between 1 and [n]."	Quantity outside range
E-RET-02	"This order is past the 30-day return window. Contact us if you need help."	Window expired
E-RET-03	"Choose a reason for the return."	No reason selected
E-RET-04	"Comments can be up to 500 characters."	Comment too long
I-RET-01	"Return [number] created. We have emailed your return label."	Return created

5.1.9 Data fields

Field	Type	Length / format	Required	Default	Source / notes
return_id	String	RET-YYYYMMDD-nnnn	Yes	Generated	System
order_id	String	ORD-nnnnnnnn	Yes	From order	Orders
line_items	List	1 to 50 items	Yes	None	Customer selection
reason_code	Enum	RET_REASON values	Yes	None	Configuration
status	Enum	Requested, Received, Awaiting approval, Refunded, Rejected, Refund failed	Yes	Requested	System
refund_amount	Decimal	10,2	Yes	Calculated	BR-RET-02

5.1.10 Acceptance criteria

AC-RET-01: Given a delivered order within 30 days, when the customer returns one item with a reason, then a return is created with status Requested and a label email is sent.
AC-RET-02: Given a delivered order 31 days old, when the customer opens it, then "Return items" is not available and E-RET-02 is explained.
AC-RET-03: Given a refund of 250, when an agent approves, then the status becomes Awaiting approval and a supervisor is notified.

5.2 [F-nn Feature name]

[Repeat the structure of 5.1 for each feature: description, actors and preconditions, main flow, alternate flows, business rules, validation rules, UI elements, messages, data fields, acceptance criteria.]

6. Reporting

ID	Report	Audience	Filters	Columns	Refresh
RPT-01	Example: Returns by reason	Operations	Date range, category	Reason, count, refund value, % of orders	Daily
RPT-02	Example: Refunds pending approval	Supervisors	Team	Return ID, age, amount, agent	Real time
[RPT-nn]	[Report]	[Audience]	[Filters]	[Columns]	[Refresh]

7. Notifications

ID	Trigger	Recipient	Channel	Content summary	Opt-out
N-03	Example: Refund completed	Customer	Email	Amount, method, expected days to appear	No (transactional)
N-04	Example: Refund above agent limit	Supervisor	In-app, email	Return ID, amount, agent	No
N-05	Example: Return rejected	Customer	Email	Reason, next steps	No
[N-nn]	[Trigger]	[Recipient]	[Channel]	[Content]	[Yes / No]

8. Integrations

ID	System	Purpose	Direction	Trigger	Failure behaviour
INT-01	Example: Payment provider	Issue refunds	Out	Refund approved	Status Refund failed; retry up to 3 times
INT-02	Example: Warehouse system	Confirm parcel receipt	In	Parcel scanned	Manual receipt by agent
[INT-nn]	[System]	[Purpose]	[In / Out]	[Trigger]	[Behaviour]

9. Non-functional summary

Area	Requirement	Reference
Performance	Example: Return request confirmation within 2 s at p95	[NFR-PERF-03]
Availability	Example: 99.9% monthly for customer-facing functions	[NFR-AV-01]
Security	Example: Refund approval requires re-authentication within the last 15 min	[NFR-SEC-07]
Accessibility	WCAG 2.2 level AA	[NFR-ACC-01]
Privacy	Example: Return comments are deleted after 2 years	[NFR-PRIV-02]

10. Acceptance criteria summary

Feature	Acceptance criteria	Test cases	Status
F-04	AC-RET-01, AC-RET-02, AC-RET-03	TC-RET-001 to TC-RET-012	[Not run / Passed / Failed]
[F-nn]	[AC IDs]	[TC IDs]	[Status]

11. Open issues and decisions

ID	Issue or decision	Owner	Due	Status / outcome
OI-01	Example: Should store credit be offered when card refund fails?	Product owner	YYYY-MM-DD	[Open]
DEC-01	Example: Partial refunds allowed per line, not per unit	Product owner	YYYY-MM-DD	Decided
[ID]	[Issue]	[@name]	YYYY-MM-DD	[Status]

12. Appendices

12.1 Glossary

Term	Definition
Return window	Number of days after delivery during which a return can be requested
Store credit	Balance usable for future orders instead of a card refund
[Term]	[Definition]

12.2 Configuration tables

Table	Values	Maintained by
RET_REASON	Damaged, Wrong item, No longer needed, Size or fit, Other	Administrator
[Table]	[Values]	[Role]

Standard and licence note

Based on common industry practice for functional specification documents in business analysis and software delivery. Original text written for this collection; examples are illustrative. Template licence: MIT.

Plantillas relacionadas

Requisitos y análisis