Creating SysML Requirement Diagrams in Mermaid.js

#mermaid #sysml #uml #markdown

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
FunctionalRequirement
InterfaceRequirement
PerformanceRequirement
PhysicalRequirement
DesignConstraint

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.