Creating SysML Requirement Diagrams in Mermaid.js
Tags: mermaid, sysml, uml, markdown
Published: 2023-04-18 03:31:10

---
title: Creating SysML Requirement Diagrams in Mermaid.js 
published: true
series: Mermaid.js
description: Let&#8217;s take a look at SysML Requirement Diagrams and see how Mermaid.js can render complex diagrams from simple markdown.
tags: Mermaid, SysML, UML, Markdown
canonical_url: https://newdevsguide.com/2023/04/17/mermaid-requirement-diagrams/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/scq7tuw21tynidl8eb4r.png
---

[Mermaid.js](https://mermaid.js.org) is a powerful diagramming library built on JavaScript that can convert simple markdown into full diagrams. While it supports many common diagram types such as [sequence diagrams](https://newdevsguide.com/2023/04/10/mermaid-sequence-diagrams/), [mind maps](https://newdevsguide.com/2023/04/14/mermaid-mind-maps/), [entity relationship diagrams](https://newdevsguide.com/2023/04/08/creating-erds-with-mermaid/), and [sequence diagrams](https://newdevsguide.com/2023/04/10/mermaid-sequence-diagrams/), it also supports a few I've rarely seen before, including the SysML Requirement Diagram.

In this article we'll explore using Mermaid.js to create a basic SysML Requirement Diagram and also introduce requirement diagrams in general as we go.

Unlike the other articles I've written on Mermaid.js, I should note that I've not had the chance to use SysML Requirement Diagrams before in the workplace. but after investigating them a bit more, I see some interesting potential in certain scenarios.

Because of my limited experience, my advice in this article will be more on how to use the Mermaid.js tooling instead of how to apply requirement diagrams to your work. If you'd like a more in-depth exploration of requirement diagrams in general, I recommend [this article from the requirement engineering magazine](https://re-magazine.ireb.org/articles/modeling-requirements-with-sysml).

Creating a Requirement Element
------------------------------

The first thing we'll need to do to create a requirement diagram is start in an editor that supports Mermaid.js markdown. [Polyglot Notebooks](https://newdevsguide.com/2022/12/14/polyglot-notebooks-csharp/), Github markdown, [Obsidian](https://obsidian.md/), and the [Mermaid Live Editor](https://mermaid.live/) all support requirement diagrams as of this writing.

Next, we'll start a diagram out with a single requirement for a dark theme:

```
requirementDiagram

requirement dark_theme {
    id: 1
    text: We need darkness
    risk: low
    verifymethod: inspection
}
```


![A simple requirement](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-89.png?resize=214%2C211&ssl=1)Here `dark_theme` is an *element* in the requirement diagram and has an `id`, `text`, `risk`, and `verifymethod` associated with it.

`id` should be something that uniquely identifies the requirement in various documentation.

`Text` is some additional contextual information about the element beyond a simple name.

`Risk` represents the risk the requirement poses and must be one of either `low`, `medium`, or `high`.

`Verification` governs how you plan on knowing the requirement is correctly fulfilled and is one of the following values:

- `Analysis` - analysis will determine that the requirement was correctly fulfilled. For example, traffic volumes &amp; bounce rates.
- `Demonstration` - we should be able to demonstrate the requirement to a product owner or other stakeholder
- `Inspection` - detailed inspection of the requirement in its functional state should be able to mark it as correct or incorrect
- `Test` - a testing process can reveal flaws or correctness in the fulfilled requirement

Additionally, note the word `requirement` before the name of our requirement. This governs which *type* of requirement the elemement is.

Supported requirement types include:

- `Requirement`
- `Functional`Requirement
- `InterfaceRequirement`
- `Performance`Requirement
- `Physical`Requirement
- `Design`Constraint

Requirement Diagram Elements
----------------------------

Now that we've covered how to compose an individual requirement, let's take a look at adding elements to our requirement diagrams in Mermaid.js.

In requirement diagrams you will often want to list specific implementations of something to associate them with various requirements they must meet and constraints they must satisfy.

These implementation parts are called *elements* and can be defined in a requirement diagram with slightly less syntax than we used for a full requirement:

```
requirementDiagram

interfaceRequirement dark_theme {
    id: 1
    text: Dark Themes Rule!
    risk: low
    verifymethod: inspection
}

element revised_skin {
    type: css,
    docRef: theme.css
}
```


![A requirement and element with no relationship](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-90.png?resize=526%2C220&ssl=1)Here we have an *element* named `revised_skin` that has only a pair of properties: `type` and `docRef`. These properties are plain-text and can be whatever is appropriate to your solution.

Note that this code also changed the `dark_theme` element from a standard requirement to an interface requirement. This is unnecessary, but more accurate in this example.

Relating Requirement Elements
-----------------------------

Now that we've shown how to create requirements and elements, let's take a look at how we can relate elements to each other.

To relate a requirement and/or element to each other, you declare their names with a descriptive arrow between the two items as shown below:

```
revised_skin - satisfies -> dark_theme
```


This creates a relationship on the requirement diagram and uses the `satisfies` label to describe that relationship.

In Mermaid.js SysML Requirement Diagrams you must choose a label and that label must be one of the following options:

- `contains`
- `copies`
- `derives`
- `satisfies`
- `verifies`
- `refines`
- `traces`

Putting it all together and adding a number of shapes in the process, we get the following more complex requirement diagram:

```
requirementDiagram

interfaceRequirement dark_theme {
    id: 1
    text: Dark Themes Rule!
    risk: low
    verifymethod: demonstration
}

performanceRequirement load_time {
    id: 2
    text: 200ms or less
    risk: medium
    verifymethod: test
}

functionalRequirement accessibility {
    id: 3
    text: Contrast
    risk: low
    verifymethod: inspection
}

element revised_skin {
    type: css,
    docRef: theme.css
}


element perf_test {
    type: unit test,
    docRef: LoadTest.cs
}

revised_skin - satisfies -> dark_theme
revised_skin - satisfies -> accessibility
revised_skin - satisfies -> load_time
perf_test - verifies -> load_time
```


![A series of requirements and element relationships](https://i0.wp.com/newdevsguide.com/wp-content/uploads/2023/04/image-91.png?resize=866%2C515&ssl=1)Here we see that Mermaid.js lets us map out networks of requirements and elements. This lets us illustrate how we are verifying and fulfilling functional, design, and performance requirements in our software systems.

Closing Thoughts
----------------

Requirement diagrams in Mermaid.js are interesting, but I'm not sure how much I'm personally interested in using them due to a few key reasons:

Mermaid.js requirement diagrams are very opinionated about the properties each requirement can have, what is displayed, and what values are acceptable. This limits your ability to customize these charts to fit your organization's needs.

Additionally, Mermaid.js requirement diagrams frequently overflow the bounding box of the requirement rectangle as shown in a few places on the last diagram above. This results in diagrams that don't look very professional.

While I love the idea of a requirement diagram in Mermaid.js, I have a lot of trouble seeing how this would regularly fit into my workflow as opposed to representing requirements in a [flowchart](https://newdevsguide.com/2023/04/15/mermaid-flowcharts/) or even [class diagram](https://newdevsguide.com/2023/04/08/mermaid-class-diagrams/).

However, that's just my own opinion and I'd love to hear what *you* think about Mermaid.js SysML Requirement Diagrams.