Mermaid.js 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, mind maps, entity relationship diagrams, and 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.
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, Github markdown, Obsidian, and the Mermaid Live Editor 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
}
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 & 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
}
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
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 or even class diagram.
However, that's just my own opinion and I'd love to hear what you think about Mermaid.js SysML Requirement Diagrams.
Top comments (1)
I've not heard of SysML diagrams before, but they certainly look cool. The layout engine looks like it's quite clever too.