Mermaid Requirement Diagram Tutorial: Model Requirements and Traceability

In systems and safety-critical engineering, a requirement is only as good as its traceability: which part of the design satisfies it, which test verifies it, and which higher-level requirement it derives from. Losing that thread is how requirements quietly go unmet. Mermaid's "requirementDiagram", based on the SysML requirements notation, lets you model this as text - declaring requirements with their risk and verification method, declaring the elements that fulfill them, and drawing the relationships that connect the two.

This guide covers the requirement diagram syntax, including the requirement types, the risk and verification attributes, and the relationship keywords that create traceability. Examples are ready for the Mermaid editor at /diagram-tools/mermaid-editor, and the rendered model opens as an editable diagram in Atlas Diagram Studio at /diagrams. Because requirements evolve, keeping the model as versioned text is a real advantage, and the AI diagram generator at /diagram-tools/ai-diagram-generator can rough out a structure from a specification you paste in.

Declaring requirements

A requirement diagram begins with the keyword "requirementDiagram". You then declare each requirement as a block: a type keyword, a name, and a set of curly-braced attributes. The type can be "requirement" for a generic one, or a more specific kind such as "functionalRequirement", "performanceRequirement", "interfaceRequirement", "physicalRequirement", or "designConstraint". Choosing the right type is not decoration - it communicates what category of obligation the requirement represents, which matters when you are reviewing coverage.

Inside the block, you give the requirement an "id", a "text" describing what it demands, a "risk" level, and a "verifymethod". The risk is one of "Low", "Medium", or "High", capturing how costly it would be for the requirement to go unmet. The verify method is one of "Analysis", "Inspection", "Test", or "Demonstration", recording how you will confirm the requirement is satisfied. Together these turn a bare statement into a managed requirement with a risk profile and a verification plan attached.

Elements and relationships

Requirements do not exist in isolation - they are satisfied by design elements and verified by tests. You declare those with the "element" keyword, giving each a name, a "type" such as "simulation" or "test," and optional attributes. Then you connect requirements and elements with relationship keywords that create the traceability web. The bullets below cover the declarations and relationships you will use most.

• Declare a requirement with a type, name, and block: "functionalRequirement login_req { ... }".
• Give it "id", "text", "risk: High", and "verifymethod: Test" inside the block.
• Declare a fulfilling element: 'element auth_module { type: "module" }'.
• "- satisfies ->" links an element to the requirement it satisfies.
• "- verifies ->" links an element (like a test) to the requirement it verifies.
• "- derives ->" links a requirement to a higher-level one it is derived from.
• "- refines ->", "- traces ->", and "- contains ->" capture the other SysML relationship kinds.
• Relationships are written as "source - relationship -> destination" on their own lines.

Building real traceability

The whole payoff of a requirement diagram is answering coverage questions at a glance. Once the relationships are in place, you can see which requirements have a satisfying element and which do not - an orphan requirement with nothing pointing a satisfies relationship at it is a gap in the design. Likewise, a high-risk requirement with no verifies relationship is a requirement you are trusting without testing, which is precisely the situation traceability exists to prevent. The diagram makes these gaps visible instead of leaving them buried in a spreadsheet.

The derives relationship builds the hierarchy that connects high-level goals to concrete, testable requirements. A stakeholder need like "the system must be secure" derives into specific functional requirements, each of which is then satisfied and verified. Tracing that chain both ways - up from a test to the goal it ultimately serves, and down from a goal to the tests that confirm it - is what gives reviewers and auditors confidence that nothing fell through. Keeping the model in version control means each change to the requirements is reviewed like any other change.

When a requirement diagram fits

Requirement diagrams earn their formality in domains where traceability is a genuine obligation: safety-critical systems, regulated industries, hardware-software systems, and any project where an auditor will ask "show me the test that verifies this requirement." For a small web feature the ceremony is overkill, and a checklist serves better. The signal that you have crossed into requirement-diagram territory is when the cost of a missed requirement is high and someone external needs evidence of coverage.

Because it is Mermaid, the model lives next to the code and specs it describes and updates in the same reviews. Author it in the Mermaid editor at /diagram-tools/mermaid-editor and refine it in Atlas Diagram Studio at /diagrams, pairing it with C4 diagrams from /diagram-tools/c4-diagram for architecture and sequence diagrams for behavior. The complete Mermaid guide at /guides/mermaid-js-complete-guide and the guide on documenting software with diagrams cover how requirement models fit into a broader engineering documentation set.