Markup in SysML v2: Keeping the Documentation in Model-Based Systems Engineering

Model-Based Systems Engineering has long promised to replace document-centric systems engineering workflows, and SysML v2 has some thoughtful design decisions that feel built to deliver on that promise. When we were working through implementing the SysML v2 spec during development, certain sections caused us to double-take – not because they were confusing, but because we were excited about the possibilities they implied. The annotation spec was one of those moments.

The passage that caught our attention is the following:

"The body text of a comment can include markup information (such as HTML), and a tool may graphically display such text as rendered according to the markup. However, marked up 'rich text' for a comment is stored in the comment body in plain text including all mark up text..."

SysML v2 has a lot of thoughtful design decisions baked into it, and this is a great example. The spec opens the door for rich, human-readable annotation content while keeping the underlying file format completely in plain text. That combination of expressive rendering without sacrificing portability is exactly the kind of thing that gets us excited about what SysML v2 makes possible.

So in SysGit, we decided that comments and anntatoins not only “can include markup information”, they should include markup information:

SysGit can render annotation body text as both HTML and Markdown, right in the tool.

With this approach, the model stays portable. The raw .sysml file contains exactly what you typed, markup and all. There’s  no hidden encoding, no binary blobs, and no proprietary format. But a capable tool (like SysGit) can take that plain text and do something genuinely useful with it using industry standards like HTML and Markdown.

What This Looks Like in Practice

Write an annotation (like a doc or a comment) in your .sysml file like this:

package Requirements {
    requirement <'REQ-017'> 'Sun-Synchronous Orbit Insertion' {
    
        doc
        /* @markdown
         * The launch vehicle **shall** deliver the spacecraft to a 
         * sun synchronous orbit with the following orbital elements 
         * at separation:
         * 
         * | Parameter | Value | Tolerance |
         * | --------- | ----- | --------- |
         * | Altitude | 550 km | ± 5 km |
         * | Eccentricity | 0.001 | ± 0.0005 |
         * | Inclination | 97.6° | ± 0.1° |
         * | RAAN drift rate | 0.9856°/day | ± 0.01°/day |
         * | Local Solar Time (descending node) | 10:30 | ± 15 min |
         */
    }
}

And you can see this rendered as MarkDown in your nodes. Headers become headers. Bold becomes bold. The table becomes a table. Links are clickable. The same works for HTML, for teams that want finer control over formatting or are generating annotations programmatically.

What You See is What You Get

We didn't want rich text annotations to be a feature only for people comfortable writing HTML or Markdown by hand, so we even added a WYSIWYG editor. Bold, italics, headers, lists, links – all available through a familiar editing interface that writes the markup for you behind the scenes. The .sysml file still stores plain text with the markup included, exactly as the spec describes. The WYSIWYG is just a friendlier way to get there.

And if you were wondering, the answer is yes, we also added image support. You can embed images directly into an annotation. And as an added benefit, since your model lives in a Git repository, those images are version controlled alongside everything else! A picture of a hardware interface. A diagram from a PDR. A screenshot of a test result. All of it can live in the annotation, tied to the specific model element it belongs to, tracked through the same commit history as your .sysml files. Simply load an image using the WYSIWYG, and SysGit takes care of the rest!

Keeping the Documentation in MBSE

There's a tension that anyone who's worked on a model-based program knows well. The model exists, the team invested in it, but gradually the real engineering conversations migrate back to Word documents and PowerPoint decks. The model becomes an artifact of record rather than a living engineering tool. Reviews happen off slides. Decisions get documented in memos. The model trails behind, updated manually to reflect what the documents already said.

It's understandable why this happens. Documents are expressive. You can write rationale, embed images, or format a table so it actually communicates something. A requirement in a traditional MBSE or requirements management tool can often just be a shall-statement and a verification method; the context that makes it meaningful lives somewhere else, in a separate document that drifts out of sync.

Rich text annotations and markup in SysML v2 don't fully close that gap on their own, but they bring us closer to that elusive state of synchronization.When the rationale for a requirement can sit in the requirement, formatted and readable, or when an engineer can embed a diagram or a test result directly in the model element it belongs to, the pull toward external documents weakens a little. The model becomes a more complete record of engineering thinking, not just engineering outputs.

This is one of the reasons we were so drawn to this part of the spec when we encountered it. SysML v2 is clearly designed by people who understood that MBSE adoption fails when the model can't carry the full weight of engineering communication. Rich text annotations are a small but meaningful piece of that – a signal that the language itself is trying to meet engineers where they actually work.