Requirement diagrams: elements and relations

简介 / Introduction

A Requirement Diagram visualizes the traceability between system requirements and design elements. It maps business requirements to interfaces, classes, and modules, helping teams verify that each requirement is correctly implemented. This article compares PlantUML and Mermaid for drawing requirement diagrams.

PlantUML version

PlantUML uses requirement, interface, element, and requirementdiagram keywords to draw requirement diagrams, supporting nested attributes, grouping, and element associations.

@startuml
requirement Req_Login "User must be able to log in" {
    id = 1
    status = approved
    verification = test
}

interface IAuthService {
    +authenticate(user, pass): boolean
    +logout()
}

element LoginForm
element AuthService

LoginForm -> IAuthService : uses
IAuthService -right-> Req_Login : satisfies
AuthService ..> IAuthService : implements

package "Business Layer" {
    requirement Req_Data "Data must be persisted" {
        id = 2
    }
    element DataStore
    DataStore --> Req_Data
}

@enduml

Mermaid version

Mermaid v11 ships with requirementDiagram built-in. The syntax follows a declarative structure: requirement + element + relationships, keeping diagrams concise and readable.

requirementDiagram
    requirement Req_Login {
        id: 1
        text: "User must be able to log in"
        status: approved
        verification: test
    }

    requirement Req_Data {
        id: 2
        text: "Data must be persisted"
        status: approved
    }

    interface IAuthService {
        type: interface
    }

    element LoginForm {
        type: user interface
    }

    element AuthService {
        type: component
    }

    element DataStore {
        type: database
    }

    LoginForm --> IAuthService
    IAuthService --> Req_Login
    AuthService ..> IAuthService
    DataStore --> Req_Data

对比 / Side-by-side

Feature	PlantUML	Mermaid
Keywords	`requirement`, `interface`, `element`, `package`	`requirement`, `interface`, `element`
Attribute block	`{ id = 1; status = approved }`	`{ id: 1; text: "..."; status: approved }`
Package/grouping	`package "Name" { ... }`	Not supported (organize via element naming)
Relationship arrows	`->`, `--->`, `..>`	`-->`
Nested relations	Multi-level nesting supported	Flat list, connected via relationships
Diagram direction	Left-to-right by default	Top-to-bottom by default

小结 / Wrap-up

PlantUML requirement diagrams offer greater flexibility for complex systems with multi-level nesting and package organization. Mermaid’s requirement diagram is lighter and its declarative syntax is faster to learn. Both can map requirements to elements for traceability — choose based on your existing toolchain.