Beauty Diagram
Diagram type

Mermaid Requirement Diagram Syntax & Examples

Reference for Mermaid requirement diagram syntax — requirement blocks (id, text, risk, verifymethod), element types, and relationships (derives, verifies, satisfies). Copy-paste examples.

Use this page to connect a high-intent search query to the right problem-solution narrative.

At a glance

A syntax reference for Mermaid's `requirementDiagram` grammar — read this when you need the exact syntax for declaring a requirement, its risk and verification method, or a derivation / verification relationship.

What is a Mermaid requirement diagramBasic syntax — requirementDiagram + blocksRequirement metadata — id, text, risk, verifymethodElement types — test_case, design_doc, etc.Relationships — derives, satisfies, verifies, refines, tracesCommon patterns & gotchas
Rendered proof
Requirement with a derived sub-requirement and a test element.
Theme · Modern
Open this diagram in editor
This example could not be rendered in the proof block. The source is still available below.
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
diagram.mmd
1requirementDiagram
2  requirement login_req {
3    id: 1
4    text: Users can sign in with email and password
5    risk: high
6    verifymethod: test
7  }
8  requirement mfa_req {
9    id: 1.1
10    text: Users must complete MFA on new devices
11    risk: medium
12    verifymethod: test
13  }
14  element login_test {
15    type: test_case
16  }
17  login_req - derives -> mfa_req
18  login_test - verifies -> login_req

What is a Mermaid requirement diagram

A requirement diagram captures formal system requirements and ties them to the elements (test cases, design artefacts, sub-requirements) that satisfy and verify them. Mermaid's implementation follows the SysML requirement diagram convention. It is the right shape when compliance, traceability, or cross-team accountability matters and specifications already live in text — regulated software (medical, aviation, automotive), enterprise systems with audit requirements, complex products where one high-level requirement decomposes into many sub-requirements. For lightweight feature planning, a simpler issue tracker or backlog usually works better; requirement diagrams pay off when traceability between layers is mandatory.

Basic syntax — requirementDiagram + blocks

Every requirement diagram starts with `requirementDiagram`. The two main building blocks are `requirement <name> { ... }` (the requirement itself) and `element <name> { ... }` (the artefact that satisfies or verifies a requirement). Both blocks declare metadata inside their braces. Relationships are declared on their own lines: `requirement_a - derives -> requirement_b`. Mermaid auto-creates the visual hierarchy from the relationships, so requirements that derive from others render below their parent.

  • `requirementDiagram` — diagram type keyword
  • `requirement <name> { ... }` — formal requirement block
  • `element <name> { ... }` — artefact (test case, design doc) block
  • `a - relationship -> b` — relationship between two named items

Requirement metadata — id, text, risk, verifymethod

Inside a requirement block, four fields are conventional. `id: <value>` is the formal identifier (often hierarchical: `1`, `1.1`, `1.1.2`). `text: <description>` is the human-readable requirement statement. `risk: <level>` is one of `low`, `medium`, `high` — used by reviewers to prioritise scrutiny. `verifymethod: <method>` is one of `test`, `analysis`, `inspection`, `demonstration` — describes how the requirement will be confirmed satisfied. The verifymethod and risk together feed compliance audits: which high-risk requirements get verified by test vs by inspection.

  • `id: <value>` — formal identifier (hierarchical numbering is common)
  • `text: <description>` — human-readable requirement statement
  • `risk: low | medium | high` — review priority signal
  • `verifymethod: test | analysis | inspection | demonstration` — how it will be verified

Element types — test_case, design_doc, etc.

Element blocks have a single required field: `type: <category>`. Common element types are `test_case` (a test that verifies a requirement), `design_doc` (a design artefact that satisfies a requirement), `requirement_doc` (referenced source spec), and `simulation` (a model that demonstrates a requirement). Custom types are allowed — the type field is freeform text. Element blocks can also have a `docref:` field for the location of the actual document, useful when the diagram is part of a traceability matrix that needs to link to source files.

Relationships — derives, satisfies, verifies, refines, traces

Mermaid supports the SysML relationship vocabulary. `derives` means one requirement is derived from another (a child requirement breaks down a parent). `satisfies` means an element fulfills a requirement (a design doc satisfies a need). `verifies` means an element confirms a requirement is met (a test case verifies a behaviour). `refines` means one item adds detail to another. `traces` is the weakest relationship — for items that should travel together without strong dependency. Each relationship has a directional meaning, so the source and target order matters: `test_case - verifies -> requirement` not `requirement - verifies -> test_case`.

  • `derives` — child requirement breaks down a parent requirement
  • `satisfies` — element fulfills a requirement (design / implementation link)
  • `verifies` — element confirms a requirement is met (test / inspection link)
  • `refines` — adds detail without strict dependency
  • `traces` — items related but without strong dependency

Common patterns & gotchas

Three patterns dominate real requirement diagrams. Top-down decomposition shows a high-level requirement breaking into sub-requirements via `derives` — useful for system-level specs. Verification matrices link each requirement to one or more `test_case` elements via `verifies` — useful for compliance evidence. Cross-cutting concerns (security, performance, accessibility) appear as elements that satisfy multiple requirements at different levels. The most common gotcha: requirement diagrams get dense quickly — keep each diagram focused on a single concern or system area. Splitting one 50-requirement diagram into five 10-requirement diagrams (each scoped to a subsystem) reads dramatically better.

  • Keep diagrams scoped — 10-15 requirements per diagram is the practical limit
  • Relationship direction matters: `element - verifies -> requirement` (verifier on the left)
  • Use hierarchical ids (1, 1.1, 1.1.2) for traceability matrices
FAQ

Mermaid Requirement Diagram Syntax & Examples — frequently asked questions

What's inside a Mermaid requirement block?

Four conventional fields: `id` (formal identifier, often hierarchical like 1.1.2), `text` (the human-readable requirement statement), `risk` (low / medium / high — review priority signal), and `verifymethod` (test / analysis / inspection / demonstration — how it'll be confirmed). All four are inside the `requirement <name> { ... }` block. The verifymethod and risk together drive compliance audits: high-risk requirements verified by test typically need more scrutiny than low-risk ones verified by inspection.

What relationships can connect requirements and elements?

Five standard SysML relationships: `derives` (child requirement breaks down a parent), `satisfies` (element fulfills a requirement — design / implementation link), `verifies` (element confirms a requirement is met — test / inspection link), `refines` (adds detail without strict dependency), `traces` (weakest — items related but without strong dependency). Direction matters: write the relationship as `source - relationship -> target`, so a test case verifies a requirement is `test_case - verifies -> requirement` (verifier on the left).

How do I link a requirement to a test case?

Declare both as separate blocks, then connect with the `verifies` relationship. Example: `requirement login_req { id: 1 text: "Users sign in with email" risk: high verifymethod: test }` plus `element login_test { type: test_case }` plus `login_test - verifies -> login_req`. The test case appears as a separate node connected to the requirement, and the relationship label tells reviewers that the test is the verification mechanism. Multiple tests verifying one requirement just add more `element` blocks and `verifies` relationships.

Should I put all my requirements in one diagram?

No. Requirement diagrams get dense quickly — keep each diagram scoped to 10-15 requirements maximum, focused on a single concern or subsystem. Splitting one 50-requirement diagram into five 10-requirement diagrams (per subsystem or per audit area) reads dramatically better. Use the surrounding documentation or a separate traceability matrix to link the diagrams together. The diagram's purpose is to show one tree of derivation and verification at a time, not to be the entire requirements database.

When is a requirement diagram overkill?

When you're doing lightweight feature planning. Issue trackers, simple backlogs, and bullet-point specs cover most product work without needing the formal SysML structure. Requirement diagrams pay off when traceability is mandatory: regulated software (medical, aviation, automotive), enterprise systems with audit requirements, safety-critical products where one high-level requirement must decompose into many provably-verified sub-requirements. If your team isn't subject to those constraints, a flowchart or class diagram usually communicates the same content more efficiently.