1. 
Feature / Functional Spec
When: At the very start of a project or feature, before any design or code begins.
Who writes it: Product Managers, Tech Leads, or Architects.
Who reads it: Everyone — designers, developers, QA, stakeholders.
Purpose: Answers the question “What are we building and why?” It’s the source of truth for the whole team to align on before work starts.
Real scenario: A PM wants to add a login feature. Before any developer touches code, they write a functional spec listing what login should do, what’s out of scope, and what the rules are (e.g., password requirements). Developers refer back to this when they have questions.
Describes what the system should do in plain, structured language.
feature-spec.md
# Feature: User Authentication
## Overview
Allow users to register, log in, and log out of the application.
## Goals
- Secure user identity management
- Session-based access control
## Actors
- Unauthenticated User
- Authenticated User
## Functional Requirements
- FR-01: Users can register with an email and password
- FR-02: Passwords must be at least 8 characters and include a number
- FR-03: Users can log in with valid credentials
- FR-04: Users receive a JWT token on successful login
- FR-05: Users can log out and invalidate their session
## Non-Functional Requirements
- NFR-01: Login must respond within 200ms under normal load
- NFR-02: Passwords must be stored as bcrypt hashes
## Out of Scope
- OAuth/SSO login (deferred to v2)
2. 🌐 API / Interface Spec (OpenAPI)
When: After the functional spec is agreed on, during the design phase, before backend or frontend code is written.
Who writes it: Backend developers or API designers.
Who reads it: Frontend developers, mobile developers, QA engineers, external API consumers.
Purpose: Answers “What does the API look like exactly?” — the endpoints, request/response shapes, and error codes. Both frontend and backend can work in parallel because the contract is agreed up front.
Real scenario: A backend dev and frontend dev are building a login page together. Instead of waiting for the backend to be done, they write an OpenAPI spec first. The frontend mocks the API using the spec and builds the UI immediately, while the backend builds to the same spec. They meet in the middle.
Describes the contract of an API endpoint.
auth-api-spec.yaml
openapi: 3.0.0
info:
title: Auth API
version: 1.0.0
paths:
/auth/login:
post:
summary: Log in a user
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
format: email
password:
type: string
minLength: 8
responses:
"200":
description: Login successful
content:
application/json:
schema:
type: object
properties:
token:
type: string
"401":
description: Invalid credentials
3. 🥒 Behavioral Spec (BDD / Gherkin)
When: During the planning/refinement phase, written alongside or just after the functional spec — before test code or implementation code is written.
Who writes it: QA Engineers, developers, and sometimes PMs (it’s meant to be readable by non-technical people).
Who reads it: Developers (to know what to implement), QA (to automate tests), and stakeholders (to verify the right thing is being built).
Purpose: Answers “How should the system behave in specific situations?” These scenarios become automated acceptance tests using tools like Cucumber or Behave.
Real scenario: Before a developer writes a single line of login code, a QA engineer writes Gherkin scenarios for “successful login”, “wrong password”, “account locked”, etc. Developers implement code until all scenarios pass — the spec drives completion.
Describes behavior using human-readable scenarios — these can be directly run as tests.
login.feature
Feature: User Login
Scenario: Successful login with valid credentials
Given a registered user with email "<span
data-original-string='pns9+VtwG/nfmZx1Gu4k/g==e8c4fUU3D6lR7EqRv/XjP7aqITVbcUlRBTa/x0QEAzc0Tw='
class='apbct-email-encoder'
title='This contact has been encoded by Anti-Spam by CleanTalk. Click to decode. To finish the decoding make sure that JavaScript is enabled in your browser.'>us<span class="apbct-blur">**</span>@<span class="apbct-blur">*****</span>le.com</span>" and password "Secret123"
When the user submits the login form
Then they should receive a JWT token
And they should be redirected to the dashboard
Scenario: Failed login with wrong password
Given a registered user with email "<span
data-original-string='1+h54H7o/IlKR25u6JFKrw==e8cM0Ja2gT8hhINRrMBEJHbxvmfV8tZNqb96cA7cN7JwxY='
class='apbct-email-encoder'
title='This contact has been encoded by Anti-Spam by CleanTalk. Click to decode. To finish the decoding make sure that JavaScript is enabled in your browser.'>us<span class="apbct-blur">**</span>@<span class="apbct-blur">*****</span>le.com</span>"
When the user submits the login form with password "wrongpass"
Then they should see an error: "Invalid credentials"
And no token should be issued
4. 🗄️ Data / Schema Spec
When: During the design phase, when you need to define what data looks like as it moves between services, databases, or APIs.
Who writes it: Backend developers, data engineers, or architects.
Who reads it: Any developer touching that data — frontend, backend, data pipelines, ML engineers, etc.
Purpose: Answers “What shape is the data?” It prevents bugs caused by one service sending userId as a number while another expects it as a string.
Real scenario: A team has a frontend app, a backend API, and a data analytics pipeline — all consuming user data. They agree on a JSON Schema up front. Any service that produces or consumes a
Userobject validates against this schema automatically, catching mismatches early.
Defines the shape of data flowing through the system.
user-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "User",
"type": "object",
"required": ["id", "email", "passwordHash", "createdAt"],
"properties": {
"id": { "type": "string", "format": "uuid" },
"email": { "type": "string", "format": "email" },
"passwordHash": { "type": "string" },
"createdAt": { "type": "string", "format": "date-time" }
}
}
🗺️ How They Fit Together in a Timeline
Quick Reference Table
| Spec Type | Written By | Used By | Answers |
|---|---|---|---|
| Feature Spec | PM / Tech Lead | Whole team | What are we building? |
| API Spec | Backend Dev | Frontend, QA, partners | What does the API look like? |
| Behavioral Spec | QA / Dev / PM | Devs & QA | How should it behave? |
| Data Schema Spec | Backend / Architect | All engineers | What shape is the data? |
The key insight is that each spec type unlocks parallel work and reduces back-and-forth — the later you write a spec, the more rework you risk.