EARS Format Complete Guide

Master the Easy Approach to Requirements Syntax for clear, testable specifications

Table of Contents

What is EARS Format?

EARS (Easy Approach to Requirements Syntax) is a structured method for writing clear, unambiguous software requirements. Developed by Rolls-Royce, EARS forces clarity by using specific templates that eliminate common sources of confusion in requirements documents.

AWS Kiro adopted EARS as its standard requirements format because it produces specifications that are both human-readable and machine-parseable, making them perfect for AI-assisted development.

Why EARS in Kiro?

  • Testability - Each requirement clearly states conditions and expected behavior
  • Clarity - Eliminates ambiguous language like "should", "may", or "appropriate"
  • Completeness - Forces you to specify triggers, conditions, and responses
  • AI-friendly - Structured format helps AI understand and implement requirements

Basic EARS Syntax

All EARS requirements follow this fundamental structure:

WHEN [condition] THE SYSTEM SHALL [behavior]

This simple template forces you to specify:

  • WHEN - The trigger or condition that activates the requirement
  • THE SYSTEM SHALL - What the system must do (never "should" or "may")
  • [behavior] - The specific, measurable action or response

Basic Example

❌ Vague Requirement

"The system should validate user input appropriately."

✅ EARS Requirement

WHEN a user submits a form with empty required fields THE SYSTEM SHALL display specific error messages for each missing field and prevent form submission.

Requirement Types

EARS defines several requirement patterns for different scenarios:

Ubiquitous Requirements

Always active system behaviors

THE SYSTEM SHALL [behavior]
THE SYSTEM SHALL encrypt all user passwords using bcrypt with minimum 12 rounds

Event-Driven Requirements

Triggered by specific events

WHEN [event] THE SYSTEM SHALL [behavior]
WHEN a user clicks the logout button THE SYSTEM SHALL clear the session and redirect to the login page

State-Driven Requirements

Active while in specific state

WHILE [state] THE SYSTEM SHALL [behavior]
WHILE a file is uploading THE SYSTEM SHALL display a progress bar with percentage complete

Optional Features

Features that may be included

WHERE [feature] THE SYSTEM SHALL [behavior]
WHERE dark mode is enabled THE SYSTEM SHALL use the dark color theme for all UI elements

Unwanted Behaviors

Things the system must not do

THE SYSTEM SHALL NOT [behavior]
THE SYSTEM SHALL NOT store payment card numbers in plain text

Complex Conditions

Multiple conditions with logical operators

WHEN [condition] AND [condition] THE SYSTEM SHALL [behavior]
WHEN a user is authenticated AND has admin privileges THE SYSTEM SHALL display the admin dashboard

Advanced EARS Patterns

Conditional Logic

For complex business logic, EARS supports conditional statements:

# Order Processing Example
WHEN a customer submits an order THE SYSTEM SHALL:
  IF the order total is less than $50 
    THEN add a $5 shipping fee
  ELSE IF the order total is between $50 and $100
    THEN add a $2 shipping fee  
  ELSE
    THEN provide free shipping

WHEN payment processing fails THE SYSTEM SHALL:
  - Send an email notification to the customer
  - Log the failure details for investigation
  - Retain the order in "pending payment" status for 24 hours

Performance Requirements

EARS excels at specifying measurable performance criteria:

# Performance Specifications
THE SYSTEM SHALL respond to user login requests within 2 seconds under normal load

WHEN processing batch reports THE SYSTEM SHALL:
  - Complete processing within 30 minutes for files up to 10MB
  - Provide progress updates every 10% completion
  - Allow users to cancel processing at any time

THE SYSTEM SHALL support up to 1000 concurrent users without degrading response time beyond 5 seconds

Error Handling

Specify exactly how errors should be handled:

# Error Handling Requirements
WHEN an API request fails due to network timeout THE SYSTEM SHALL:
  - Retry the request up to 3 times with exponential backoff
  - Display a user-friendly error message after all retries fail
  - Log the failure details for debugging

WHEN a user uploads an invalid file format THE SYSTEM SHALL:
  - Reject the upload immediately
  - Display specific error message listing supported formats
  - Allow the user to select a different file without losing other form data

THE SYSTEM SHALL NOT expose internal error details to end users

Real-World Examples

Here are complete EARS specifications for common application features:

User Authentication System

# User Authentication Requirements

## Login Process
WHEN a user enters valid credentials THE SYSTEM SHALL:
  - Authenticate the user against the database
  - Create a secure session token
  - Redirect to the user's dashboard
  - Log the successful login event

WHEN a user enters invalid credentials THE SYSTEM SHALL:
  - Display "Invalid username or password" message
  - Increment failed login counter for that username
  - Log the failed attempt with IP address
  - NOT reveal whether username or password was incorrect

WHEN a user account has 5 failed login attempts within 15 minutes THE SYSTEM SHALL:
  - Lock the account for 30 minutes
  - Send account lockout notification email
  - Log security event for monitoring

## Password Requirements
THE SYSTEM SHALL enforce passwords that:
  - Are at least 8 characters long
  - Contain at least one uppercase letter
  - Contain at least one lowercase letter  
  - Contain at least one number
  - Contain at least one special character

THE SYSTEM SHALL NOT accept passwords that:
  - Match the previous 5 passwords
  - Contain the username
  - Are common dictionary words

## Session Management  
WHILE a user session is active THE SYSTEM SHALL:
  - Refresh session tokens every 30 minutes
  - Track user activity timestamps
  - Automatically logout after 2 hours of inactivity

WHEN a user logs out THE SYSTEM SHALL:
  - Invalidate the session token immediately
  - Clear all session data
  - Redirect to login page

E-commerce Shopping Cart

# Shopping Cart Requirements

## Adding Items
WHEN a user clicks "Add to Cart" for an available product THE SYSTEM SHALL:
  - Add the selected quantity to the cart
  - Update cart total and item count
  - Display confirmation message with product name
  - Persist cart contents to user session or database

WHEN a user tries to add more items than available in stock THE SYSTEM SHALL:
  - Display current stock level
  - Allow adding only up to available quantity
  - Suggest alternatives or backorder options

## Modifying Cart
WHEN a user changes item quantity in cart THE SYSTEM SHALL:
  - Update cart totals instantly
  - Validate new quantity against stock levels
  - Save changes automatically
  - Recalculate shipping and tax amounts

WHEN a user removes an item from cart THE SYSTEM SHALL:
  - Remove item immediately
  - Update all totals and counts
  - Provide "undo" option for 10 seconds
  - Show updated cart summary

## Cart Persistence
THE SYSTEM SHALL preserve cart contents:
  - For 30 days for registered users
  - For duration of browser session for guests
  - Across device switches for logged-in users

WHEN a user's cart contains items no longer available THE SYSTEM SHALL:
  - Mark unavailable items clearly
  - Remove them from total calculations
  - Suggest similar alternative products
  - Allow proceeding with remaining items

Common EARS Mistakes

Avoid these frequent pitfalls when writing EARS requirements:

❌ Common Mistake ✅ Correct EARS Format Why It Matters
The system should validate input WHEN a user submits a form THE SYSTEM SHALL validate all required fields Eliminates ambiguity about when validation occurs
The system may send notifications WHEN an order status changes THE SYSTEM SHALL send email notification to customer Makes notification sending mandatory, not optional
Handle errors appropriately WHEN API call fails THE SYSTEM SHALL display user-friendly error message and log technical details Specifies exactly what "appropriate" means
Provide good user experience WHEN page load time exceeds 3 seconds THE SYSTEM SHALL display loading indicator Defines measurable criteria for "good"
System will be secure THE SYSTEM SHALL encrypt all data transmissions using TLS 1.3 Specifies concrete security measures

EARS Best Practices

Writing Guidelines

  • Be specific - Avoid vague terms like "appropriate", "reasonable", or "user-friendly"
  • Use active voice - "THE SYSTEM SHALL process" not "data will be processed"
  • Include measurable criteria - Time limits, quantities, percentages
  • Specify error conditions - Don't just describe happy path scenarios
  • One requirement per statement - Avoid compound requirements with "and"

Organizational Tips

  • Group related requirements - Use clear section headers
  • Number requirements - Makes them easier to reference and track
  • Use consistent terminology - Define terms in a glossary
  • Include rationale - Explain why the requirement is needed
  • Mark priority levels - Must-have vs. nice-to-have features

Avoid These Words in EARS

These vague terms lead to ambiguous requirements:

  • Should/May/Might - Use "SHALL" for mandatory requirements
  • Appropriate/Suitable/Proper - Specify exact criteria
  • User-friendly/Intuitive - Define measurable usability metrics
  • Fast/Quick/Slow - Provide specific time measurements
  • Large/Small/Big - Give exact sizes, quantities, or limits

Testing EARS Requirements

Well-written EARS requirements naturally translate into test cases:

From Requirement to Test

EARS Requirement

WHEN a user submits a contact form with valid data THE SYSTEM SHALL send confirmation email within 5 minutes and display success message

Derived Test Cases

Test Case 1: Valid Form Submission
- Input: Complete form with valid email, name, message
- Expected: Success message appears immediately
- Expected: Confirmation email received within 5 minutes

Test Case 2: Email Delivery Timing
- Input: Valid form submission
- Measure: Time from submission to email delivery
- Expected: ≤ 5 minutes

Test Case 3: Email Content Validation
- Input: Form with specific test data
- Expected: Email contains form data correctly
- Expected: Email sent to submitted address

Test Categories from EARS

  • Condition Testing - Verify WHEN conditions trigger correctly
  • Behavior Testing - Confirm SHALL behaviors execute as specified
  • Boundary Testing - Test limits specified in requirements
  • Error Testing - Validate error handling requirements
  • Performance Testing - Measure against specified timing requirements

EARS Testing Benefits

  • Automatic test generation - Each EARS statement suggests test scenarios
  • Complete coverage - Forces consideration of all conditions and responses
  • Measurable outcomes - Clear pass/fail criteria
  • Regression prevention - Specific requirements prevent scope creep

Integration with Kiro

Kiro's AI agents can automatically generate test suites from EARS requirements:

# In your tasks.md file:
- [ ] Generate unit tests for all EARS requirements in requirements.md
- [ ] Create integration tests for multi-step EARS workflows  
- [ ] Implement performance tests for timing requirements
- [ ] Set up automated regression testing for SHALL NOT requirements

Next Steps

Ready to implement EARS in your Kiro project?