# Requirements diagram

A requirements diagram links requirements to the things that satisfy them and the tests that verify them. It is a SysML idea, and it is useful anywhere somebody will eventually ask "how do we know this works?".

The value is in the trace links, not in the boxes.

---

## When to reach for one

* Regulated or safety-relevant work where traceability is required.
* Complex features where requirements and components map many-to-many.
* Audits, where the question is always which test covers which requirement.

---

## How to draw it in Capable

| **Route** | **Use when**                                            |
| --------- | ------------------------------------------------------- |
| PlantUML  | Requirement-style diagrams with typed relationships.    |
| draw.io   | When the diagram is for a document rather than a model. |

---

## A worked example

Requirements, what satisfies them, and what verifies them:

![Requirements diagram](https://help.gocapable.com/images/att1424130127.svg)

The source, which you can paste into a new diagram and edit:

```
@startuml
rectangle "REQ-1\nSessions expire after 30 minutes" as R1
rectangle "REQ-2\nExpiry is configurable" as R2
component "Session service" as S
component "Admin settings" as A
rectangle "TEST-14\nExpiry integration test" as T

R2 --> R1 : refines
S ..> R1 : satisfies
A ..> R2 : satisfies
T ..> R1 : verifies
@enduml
```

---

## A few things that catch people out

* Name relationships properly. Satisfies, verifies and refines mean different things.
* Give requirements stable identifiers; the diagram is worthless if the ids change.
* Keep one diagram per feature. A whole-product requirements diagram is unreadable.

---

## Related

[Event modelingCommands, events, read models, on a timeline.](https://help.gocapable.com/diagrams/event-modeling.html)

[ArchiMate diagramEnterprise architecture views with the standard notation.](https://help.gocapable.com/diagrams/archimate-diagram.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Cheap to change means it stays true._