Mermaid requirement diagram syntax: engineering specs made visual

Software projects fail not because of bad code, but because of unclear requirements. Engineers ship features that don't match what stakeholders actually needed. Requirement diagrams solve this by making specifications visual and traceable — every requirement tied to the components that satisfy it, and every acceptance criterion visible at a glance.

Mermaid's requirementDiagram gives you a lightweight, portable way to document requirements without enterprise tools. This guide walks you through the syntax, shows real examples, and explains when to use it alongside flowcharts and sequence diagrams.

What a requirement diagram shows

A requirement diagram maps three things:

1. Requirements — what the system must do (functional) or must be (non-functional)
2. Elements — the components, subsystems, or modules that satisfy requirements
3. Relationships — which element satisfies which requirement, and what tests verify it

Think of it as a "traceability matrix" made visual: you see at once which requirements are covered, which components do multiple jobs, and which elements are orphaned (building features nobody asked for).

Basic syntax

requirementDiagram

requirement REQ_1 {
  id: REQ_001
  text: Payment processing must complete within 2 seconds
  risk: high
  verifymethod: test
}

requirement REQ_2 {
  id: REQ_002
  text: System must support 10,000 concurrent users
  risk: medium
  verifymethod: load-test
}

element PAYMENT_SERVICE {
  type: software
}

element LOAD_BALANCER {
  type: hardware
}

REQ_1 - satisfiedBy -> PAYMENT_SERVICE
REQ_2 - satisfiedBy -> LOAD_BALANCER

Key parts:

• requirement blocks define what you need. Each has:

  • id: a unique identifier (e.g., REQ_001)
  • text: the requirement statement
  • risk: low, medium, or high priority
  • verifymethod: how you'll validate it (test, inspection, demonstration, load-test, etc.)

• element blocks define what builds it. Each has:

  • type: software, hardware, or interface

• Relationships connect requirements to elements:

  • REQ_1 - satisfiedBy -> ELEMENT_1
  • ELEMENT_1 - verifies -> REQ_2 (element verifies the requirement)
  • ELEMENT_1 - refines -> REQ_3 (element clarifies a requirement)
  • REQ_1 - contains -> REQ_2 (nested requirements)

Real-world example: e-commerce checkout system

Here's a complete requirement diagram for an online store's payment flow:

requirementDiagram

requirement USER_AUTH {
  id: UECOM-001
  text: Users must authenticate before checkout
  risk: high
  verifymethod: test
}

requirement PAYMENT_TIMEOUT {
  id: UECOM-002
  text: Payment processing must timeout after 30 seconds
  risk: high
  verifymethod: test
}

requirement FRAUD_CHECK {
  id: UECOM-003
  text: All transactions over $500 require fraud review
  risk: medium
  verifymethod: inspection
}

requirement INVENTORY {
  id: UECOM-004
  text: System must reserve stock during checkout
  risk: high
  verifymethod: test
}

requirement COMPLIANCE {
  id: UECOM-005
  text: Payment data must comply with PCI-DSS
  risk: high
  verifymethod: inspection
}

element AUTH_SERVICE {
  type: software
}

element PAYMENT_GATEWAY {
  type: software
}

element FRAUD_DETECTOR {
  type: software
}

element INVENTORY_DB {
  type: software
}

element TOKENIZER {
  type: software
}

USER_AUTH - satisfiedBy -> AUTH_SERVICE
PAYMENT_TIMEOUT - satisfiedBy -> PAYMENT_GATEWAY
FRAUD_CHECK - satisfiedBy -> FRAUD_DETECTOR
INVENTORY - satisfiedBy -> INVENTORY_DB
COMPLIANCE - satisfiedBy -> TOKENIZER
COMPLIANCE - refines -> PAYMENT_GATEWAY

What this shows:

• Every requirement has a corresponding component
• PAYMENT_GATEWAY satisfies the timeout requirement
• FRAUD_DETECTOR handles the $500-threshold rule
• TOKENIZER ensures compliance (and refines how PAYMENT_GATEWAY works)
• Readers see at a glance which components touch compliance (both COMPLIANCE and PAYMENT_GATEWAY)

Common patterns

Derived requirements

When one requirement breaks down into smaller sub-requirements, use contains:

requirementDiagram

requirement API_PERFORMANCE {
  id: REQ-001
  text: API must meet SLA targets
  risk: high
  verifymethod: load-test
}

requirement RESPONSE_TIME {
  id: REQ-002
  text: 95th percentile response time < 200ms
  risk: high
  verifymethod: test
}

requirement UPTIME {
  id: REQ-003
  text: 99.9% monthly uptime
  risk: high
  verifymethod: monitoring
}

API_PERFORMANCE - contains -> RESPONSE_TIME
API_PERFORMANCE - contains -> UPTIME

element API_SERVER {
  type: software
}

element CACHE_LAYER {
  type: software
}

RESPONSE_TIME - satisfiedBy -> CACHE_LAYER
UPTIME - satisfiedBy -> API_SERVER

Verification relationships

When an element both satisfies and verifies a requirement:

requirementDiagram

requirement ENCRYPTION {
  id: SEC-001
  text: All data at rest must use AES-256
  risk: high
  verifymethod: inspection
}

element CRYPTO_LIBRARY {
  type: software
}

ENCRYPTION - satisfiedBy -> CRYPTO_LIBRARY
CRYPTO_LIBRARY - verifies -> ENCRYPTION

When to use requirement diagrams

Use requirement diagrams when:

• You need to show which components satisfy which requirements
• Stakeholders and engineers need to agree on "what counts as done"
• You're documenting compliance or regulatory requirements
• You want a living traceability matrix (updated as requirements change)

Don't use when:

• Requirements are simple (use a checklist or table instead)
• You need to show how a system works (use sequence or flowchart diagrams)
• Relationships are deeply nested (switch to a requirements management tool)

Comparison with related diagram types

Diagram	Shows	Best for
Requirement	Requirements ↔ components	Traceability, compliance, spec coverage
Flowchart	Decision logic and flow	Business process, algorithms
Sequence	Interactions over time	API calls, system messaging
Class	Objects and relationships	Domain modeling, architecture

A typical project uses both requirement and sequence diagrams: requirements diagram for "what we must build," sequence diagrams for "how we'll build it."

Exporting and sharing

Requirement diagrams in Mermaid render as SVG and PNG just like any other diagram. Use MermaidCreator's export tools to save as high-resolution images for stakeholder reviews, or embed them directly in your documentation:

![Requirements for checkout system](./checkout-requirements.svg)

Or paste the diagram code into your README, GitLab/GitHub wiki, or Confluence for live rendering.

FAQ

Can I link requirements across files?
Not natively—each diagram is independent. But you can reference related diagrams via links in the document or in note comments within the diagram.

What if a requirement has no satisfying element?
That's a red flag. It means a requirement is unimplemented. Use MermaidCreator's visual editor to highlight gaps and spot unimplemented work during planning.

Can I export requirement diagrams as a traceability matrix (CSV/Excel)?
Not automatically, but you can copy the requirement text and element names into a spreadsheet for further processing. Some teams use both: a visual requirement diagram for brainstorming and a spreadsheet matrix for compliance audits.

How do I keep requirement diagrams in sync with code changes?
Commit the .md file containing the diagram alongside your code. When you refactor and remove a component, update the diagram in the same PR. Treat it like documentation that lives in git.

Start mapping your system's requirements in the MermaidCreator editor—sketch a simple feature and its components, then link them with satisfaction relationships to see the full picture.