How to Draw Requirement Diagrams in Mermaid

2026-03-05 · MermZen Tutorial

Requirement diagrams (based on SysML requirement diagrams) visualize requirements, how they relate to each other, and which system elements satisfy or verify them. They're ideal for requirements traceability in regulated or safety-relevant projects. Mermaid uses the requirementDiagram type.

Why Use Requirement Diagrams?

• Visualize requirement structure — see hierarchy and dependencies between requirements at a glance
• Traceability — associate each requirement with the elements that satisfy it and the verification method that confirms it
• Track derived/refined requirements — see how a high-level requirement breaks down into more specific ones

Use Cases

✅ Suitable: regulated or safety-relevant projects that need formal requirements traceability (SysML-style); documenting which components satisfy which requirements.

❌ Not suitable: lightweight product requirements without a traceability need — a plain list or table is simpler and faster to maintain.

Declaring a Chart

requirementDiagram

requirement user_auth {
id: 1
text: The system shall authenticate users
risk: high
verifymethod: test
}

A requirement block needs exactly these four fields: id, text, risk (high/medium/low), and verifymethod (analysis/inspection/test/demonstration). There's no type, status, or priority field — those don't exist in the real syntax, despite sounding plausible. title is also not a valid top-level statement — it breaks the render entirely (confirmed by testing), unlike architecture-beta or block-beta where an invalid title is just silently ignored.

The Six Requirement Types

Beyond the generic requirement, Mermaid supports five more specific types — same field structure, different semantic label:

requirementDiagram

interfaceRequirement api_interface {
id: 3
text: The system shall expose a REST API
risk: medium
verifymethod: inspection
}

physicalRequirement server_rack {
id: 4
text: The system shall run on redundant servers
risk: low
verifymethod: analysis
}

designConstraint tech_stack {
id: 5
text: The system shall use TypeScript
risk: low
verifymethod: analysis
}

Elements and Relationships

requirementDiagram

requirement user_auth {
id: 1
text: The system shall authenticate users
risk: high
verifymethod: test
}

element AuthService {
type: simulation
}

AuthService - satisfies -> user_auth

element id { type: ... } defines a real-world thing (a service, a document, a test case) that participates in requirement relationships. The syntax for any relationship is source - relationshipType -> target:

Requirements can also relate to each other, not just to elements:

requirementDiagram

requirement parent_req {
id: 1
text: parent requirement
risk: low
verifymethod: test
}

requirement child_req {
id: 1.1
text: child requirement
risk: low
verifymethod: test
}

parent_req - contains -> child_req

Full Example: Login Requirements Traceability

requirementDiagram

requirement user_auth {
id: 1
text: The system shall authenticate users
risk: high
verifymethod: test
}

functionalRequirement login_flow {
id: 1.1
text: The system shall provide a login form
risk: medium
verifymethod: inspection
}

performanceRequirement response_time {
id: 2
text: Login shall respond within 2 seconds
risk: low
verifymethod: demonstration
}

element AuthService {
type: simulation
}

element LoginUI {
type: simulation
}

AuthService - satisfies -> user_auth
LoginUI - satisfies -> login_flow
user_auth - contains -> login_flow
AuthService - traces -> response_time

Two elements (AuthService, LoginUI) satisfy two requirements, one requirement contains a sub-requirement, and one element traces to a performance requirement — a complete, small traceability graph.

Common Mistakes

• Using type, status, or priority fields — these don't exist. The only fields are id, text, risk, verifymethod.
• Using title — breaks the render entirely for this diagram type specifically.
• Writing requirement "Display Name" { ... } — the identifier right after requirement is a bare ID (like a variable name), not a quoted display string. Use requirement my_req { text: "Display text goes here" } instead — the human-readable text belongs in the text field.
• Making up relationship names like requires or impacts — only satisfies, verifies, traces, contains, derives, refines, copies are real.
• Hyphens in attribute values (e.g. docref: some-doc) can break parsing — avoid hyphens in attribute values, or quote them if your renderer's version supports it.

Quick Reference

Next Step

For a lighter-weight way to show relationships between concepts without SysML formality, see Mermaid Flowcharts.

To try the above code in MermZen, click Open Editor and paste the code there.