VPasCode (Diagram as Code) for SysML Requirement Diagram — A Comprehensive Guide

1. What Is a Requirement Diagram?

A requirement diagram is a SysML diagram type whose single purpose is to capture requirements as first-class model elements and make their relationships explicit and traceable. Unlike a requirements document (which is just a list), a requirement diagram is a graph: requirements are nodes, and the relationships between them — containment, derivation, satisfaction, verification, and traceability — are edges.

The core idea is traceability. In an IT system, a requirement doesn’t live in isolation. A stakeholder need drives a system requirement; that requirement is satisfied by an architectural block; a test case verifies it; and it may be refined into sub-requirements. The requirement diagram makes every one of those links visible and auditable. That is what turns a flat spreadsheet into a model.

Why use it for IT systems?

IT projects are notorious for requirements drift — scope creep, unmanaged changes, and the “we built it but nobody asked for it” problem. A requirement diagram helps because it lets you:

• Trace backward — “Why does this component exist?” → follow satisfy links up to the requirement, and derive links up to the business need.

• Trace forward — “Is this requirement verified?” → follow verify links to the test cases.

• Assess change impact — “If this requirement changes, what else is affected?” → follow every incoming and outgoing edge.

• Prove coverage — every requirement should be satisfied by something and verified by something. Orphan requirements are immediately visible.

2. Key Concepts & Notation

2.1 The requirement element

A requirement is drawn as a rectangle with a name, a unique ID (typically hierarchical, like 1.2.3), and requirement text. The stereotype is «requirement».

Requirements can contain properties — formally modeled attributes such as source, risk, priority, status, or verificationMethod. These make a requirement measurable rather than vague.

2.2 The relationships (the heart of the diagram)

The critical rule: A relationship is never drawn to a requirement’s ID string — it is drawn to the element’s alias. And if requirement A contains requirement B, you must not also draw a «derive» between them in either direction; containment and derivation are mutually exclusive for the same pair.

2.3 Blocks, test cases, and refinement sources

• Block («block»): the design element that satisfies requirements. In an IT context, this is your architectural component — a service, module, or API.

• Test case («testCase»): the verification unit.

• Refinement sources: use cases, activities, or any model element that elaborates a requirement.

Notation note: the relationship arrows have specific heads (the «satisfy» arrow, for instance, opens toward the requirement being satisfied). When writing about these in prose, always quote the stereotype — write `«satisfy»` — so it isn’t swallowed by the reader’s markdown parser.

3. Diagram Examples

Example 1 — A foundational requirement hierarchy

This example shows containment and derivation, the skeleton every requirement diagram starts with. A top-level performance requirement breaks down into measurable sub-requirements.

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title Vehicle Performance Requirement Hierarchy

$requirement("Vehicle Performance", ReqVehiclePerf, "1", "The vehicle shall meet the specified performance targets under nominal operating conditions.")
$requirement("Acceleration", ReqAccel, "1.1", "The vehicle shall accelerate from 0 to 100 km/h in under 6 seconds.")
$requirement("Top Speed", ReqTopSpeed, "1.2", "The vehicle shall reach a maximum speed of at least 220 km/h.")
$requirement("Braking", ReqBraking, "1.3", "The vehicle shall stop from 100 km/h in under 38 meters on dry pavement.")
$requirement("Fuel Efficiency", ReqFuel, "1.4", "The vehicle shall achieve at least 15 km/l on the combined cycle.")

$containment(ReqVehiclePerf, ReqAccel)
$containment(ReqVehiclePerf, ReqTopSpeed)
$containment(ReqVehiclePerf, ReqBraking)
$containment(ReqVehiclePerf, ReqFuel)
$deriveReqt(ReqBraking, ReqVehiclePerf)
@enduml

Reading it: Acceleration, Top Speed, Braking, and Fuel Efficiency are all parts of the overarching Vehicle Performance requirement (containment). Braking is also derived from it, meaning it was broken out into a concrete, measurable target.

Example 2 — Satisfaction and verification (design meets requirements)

This adds the design side. Architectural components satisfy requirements, and test cases verify them. This is the diagram you show at a design review.

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title Payment System — Satisfaction and Verification

$requirement("PCI-DSS Compliance", ReqPci, "3", "The system shall not store card verification values and shall encrypt cardholder data at rest.")
$requirement("Process Payment", ReqPay, "3.1", "The system shall authorize a customer payment within 3 seconds.")
$requirement("Idempotent Charge", ReqIdem, "3.2", "The system shall not double-charge a customer on retry.")

$block("PaymentService", PaymentService)
$block("VaultService", VaultService)

$testCase("PCI Audit", TAudit)
$testCase("Latency Test", TLatency)
$testCase("Idempotency Test", TIdem)

$containment(ReqPci, ReqPay)
$containment(ReqPci, ReqIdem)

$satisfy(PaymentService, ReqPay)
$satisfy(VaultService, ReqPci)

$verify(TAudit, ReqPci)
$verify(TLatency, ReqPay)
$verify(TIdem, ReqIdem)
@enduml

Reading it: PaymentService satisfies the payment-processing requirement, while VaultService satisfies the broader PCI-DSS requirement. Each requirement is verified by a test case. Notice the arrow directions: `«satisfy»` points from the block toward the requirement it fulfils; `«verify»` points from the test case toward the requirement it proves.

Example 3 — Full IT-system traceability chain

This is the diagram you’d use to trace a business need all the way through to verification — the classic “why does this code exist?” question.

@startuml
!include https://static.visual-paradigm.com/plantuml-stdlib/sysml-requirement-diagram.puml

skinparam vpDiagramType RequirementDiagram
skinparam defaultFontSize 14
skinparam defaultFontColor #333333
skinparam linetype ortho

title E-Commerce System — Requirement Traceability

$requirement("Business: Reduce Cart Abandonment", ReqBiz, "B1", "The business shall reduce cart abandonment by 15% within two quarters.")
$requirement("Checkout UX", ReqUx, "S1", "The system shall allow a guest to complete checkout in under 5 steps.")
$requirement("One-Click Reorder", ReqReorder, "S2", "The system shall let a returning customer reorder a past purchase in one action.")
$requirement("Data Residency", ReqResidency, "S3", "The system shall store EU customer data within EU regions.")

$block("CheckoutUI", CheckoutUI)
$block("ReorderService", ReorderService)
$block("RegionalDatastore", RegionalDatastore)

$testCase("Checkout Flow Test", TCheckout)
$testCase("Reorder Test", TReorder)
$testCase("Residency Audit", TResidency)

$containment(ReqBiz, ReqUx)
$containment(ReqBiz, ReqReorder)
$deriveReqt(ReqUx, ReqBiz)
$deriveReqt(ReqReorder, ReqBiz)

$satisfy(CheckoutUI, ReqUx)
$satisfy(ReorderService, ReqReorder)
$satisfy(RegionalDatastore, ReqResidency)

$verify(TCheckout, ReqUx)
$verify(TReorder, ReqReorder)
$verify(TResidency, ReqResidency)

$trace(ReqResidency, ReqBiz)
@enduml

Reading it: The business requirement B1 anchors everything. The system requirements S1 and S2 are derived from it (the “why”), while S3 (data residency) is a traceable constraint linked only by `«trace»`. Each system requirement is satisfied by a component and verified by a test. If B1 changes, this diagram tells you instantly which components and tests are in scope.

4. How to Build One (Practical Workflow)

1. Start with the top-level need. Normally a business or stakeholder requirement. Give it a clear ID space (e.g. B* for business, S* for system).

2. Decompose downward with containment. Break the big requirements into smaller, measurable ones. Good requirement text has a number in it (“under 3 seconds”, “15%”, “within EU regions”).

3. Add derivation links where a child is a concrete restatement, not just a part. Remember: a pair can be joined by containment or derivation, never both.

4. Map design to requirements with satisfy. Each architectural block should satisfy at least one requirement. Blocks that satisfy nothing are candidates for deletion; requirements satisfied by nothing are coverage gaps.

5. Map tests with verify. Every requirement needs a verification path. Requirements verified by nothing are untestable — a red flag.

6. Use trace only when nothing else fits. It’s the escape hatch for loose associations; overusing it dilutes the value.

7. Keep it under ~24 elements. Large diagrams become unreadable. Split by subsystem or by requirement category (security, performance, functional).

The three coverage questions

Run this checklist against every requirement diagram:

• Every requirement is satisfied? (if it’s a system requirement, something must realize it)

• Every requirement is verified? (something must prove it)

• Every requirement traces up to a need? (no orphan requirements floating with no business justification)

Any “no” is a finding.

5. Applying It to IT Systems — Patterns & Pitfalls

Good practices

• Separate requirement types visually. You can stereotype requirements («functional», «performance», «security», «usability») so non-functional requirements stand out from functional ones.

• Keep the ID hierarchy meaningful. 2.3.4 should tell a reader that this requirement lives under module 2, feature 3, sub-feature 4. Consistency across diagrams and your ALM tool matters.

• Model the source. Add a source property (regulatory, stakeholder name, market requirement doc). Traceability to origin is often more important than traceability to design.

• One diagram, one concern. A satisfaction diagram (design review) and a verification diagram (test review) have different audiences. Don’t cram both plus the whole hierarchy into one image.

Common pitfalls

• Derivation vs. containment confusion. They look similar but mean different things. Containment is structural decomposition; derivation is logical evolution of intent. Mixing them (or drawing both between a pair) makes the model invalid.

• Referencing by ID instead of alias. In the tool, relationships bind to element aliases, not the human-readable ID strings. Get the alias right or the relationship silently targets nothing.

• Treating trace as satisfy. A trace link doesn’t claim the target fulfils anything. If you mean “this component implements this requirement,” use `«satisfy»`.

• Requirements with no number. “The system shall be fast” cannot be verified. A requirement without a measurable threshold is a wish, not a requirement.

• Letting the diagram become the spec. The diagram shows relationships; the requirement text and properties carry the detail. Keep the text precise and attach properties (status, priority, risk) so the model is queryable.

6. Tooling

You can render these diagrams directly from the PlantUML source shown above using VPasCode — paste the code, and the diagram renders immediately. From there you can also export or refine it.

Quick reference: element and relationship macros

$requirement("Name", alias, "id", "Requirement text")
$block("BlockName", alias)
$testCase("TestCaseName", alias)

$containment(parentAlias, childAlias)
$deriveReqt(childAlias, parentAlias)
$satisfy(blockAlias, requirementAlias)
$verify(testCaseAlias, requirementAlias)
$refine(modelAlias, requirementAlias)
$trace(fromAlias, toAlias)
$copy(fromAlias, toAlias)

Summary

A requirement diagram is the traceability backbone of a model. For IT systems, it answers the three questions every audit, design review, and change request asks: Why does this exist? What implements it? What proves it? Used well — with measurable requirement text, correct relationship semantics, and disciplined coverage checks — it turns requirements from a static document into a living, queryable model that keeps design, code, and test aligned with business intent.

Reference

1. VPasCode: AI-Assisted Diagram-as-Code with PlantUML, Mermaid, and Graphviz: Official guide covering AI-assisted diagram generation, modification workflows, and multi-DSL support including PlantUML, Mermaid, and Graphviz.
2. Visual Paradigm VPasCode: Comprehensive Guide: Detailed overview of VPasCode features, target users (developers, architects, analysts), and its role in Agile documentation workflows.
3. Welcome to Visual Paradigm VPasCode: The Shift to Diagram-as-Code (DaC): Introduction to the unified platform, explaining the advantages of text-to-diagram workflows and automated layout engineering.
4. 60-Second Quickstart Guide | VPasCode Text to Diagram Guide: Step-by-step walkthrough for creating, customizing, and exporting diagrams using the browser-based editor with live preview.
5. New in VPasCode: AI UML Profile Diagram Generator: Product update introducing AI-powered UML Profile Diagram generation using plain English prompts, with example for healthcare data privacy compliance.
6. Native AI Diagram Generation in Visual Paradigm VPasCode: Announcement of embedded AI capabilities for generating, modifying, and fixing diagrams via natural language prompts directly in the editor.
7. AI-Powered Diagram Generator & Productivity Tools | VPasCode: Overview of VPasCode integrations with AI chatbots, Visual Paradigm Desktop, and OpenDocs for streamlined documentation pipelines.
8. Best PlantUML Alternatives & Free Diagram as Code Editors: Comparison matrix of PlantUML alternatives, highlighting VPasCode’s multi-DSL support, AI features, and browser-based zero-setup approach.
9. Diagram-as-Code Editor: Convert Text to Diagram Instantly: Feature overview covering automatic format detection, real-time rendering, and multi-format export options (SVG, PNG, PDF).
10. Guide to the Visual Paradigm Ecosystem: Explains when to use VPasCode vs. VP Desktop, with guidance on version-controlled diagram maintenance and integration with living documentation.

Related posts:

PlantUML Use Case Diagram Guide Minimum Effective UML: A Practical Guide to Modeling Software Systems Use Case Diagrams: A Practical Guide UML from What to How with Use Case and Activity Diagram