SysML v2 Textual Notation Explained: Why SysML v2 Looks Like Code (and Why That’s a Good Thing)

If you are coming from SysML v1, opening a SysML v2 model for the first time can feel disorienting. Where are the familiar boxes? Where did the lines go? And why does the model suddenly look like code?

This initial “syntax shock” is one of the most common reactions engineers have when they first encounter SysML v2 textual notation. But this shift is not accidental, and it is not a step backward. In fact, it represents one of the most important advances in model-based systems engineering (MBSE) in the last decade.

So why does SysML v2 use text instead of diagrams, and what problem is this redesign actually solving?

Textual Notation in SysML v2

In SysML v1, models were created graphically first. Diagrams were the primary interface, while the underlying model was stored and exchanged using XMI, a format optimized for tools rather than humans.

SysML v2 changes this approach entirely by introducing a standardized textual syntax that is central to the language rather than an afterthought.

This textual notation brings several practical advantages:

• Human-readable and semantically complete models SysML v2 models are defined in a standardized textual form that can be read and understood without specialized tools, while fully capturing the model’s semantics. This makes SysML v2 models easier to interpret, exchange, and reuse across tools, avoiding many of the fidelity and interoperability issues associated with XMI-based interchange in SysML v1.
• Version-control friendly workflows
  Because SysML v2 models are text, teams can use standard DevOps tools like Git to track changes, compare versions, and review diffs with clarity. This is a major improvement for collaborative systems engineering.

This shift aligns SysML v2 more closely with modern engineering workflows, where precision, traceability, and automation matter as much as visualization.

What are "part def" & "part" in SysML v2?

If you look at any SysML v2 model, you will quickly notice the frequent use of part def and part. This is one of the most visible differences between SysML v1 and SysML v2, and it reflects a deliberate shift toward clearly separating definitions from usages.

In SysML v2:

• part def defines what something is in general terms
• part represents a specific usage or occurrence of that definition within a system context

For example, a vehicle can be defined once using part def Vehicle, then reused many times as individual parts such as part myCar: Vehicle within larger system models.

For a deeper explanation, see [Lesson 3].

Does SysML v2 Replace Diagrams with Text?

For many engineers, the first question when moving to SysML v2 is whether diagrams are still used. The answer is a resounding yes. SysML v2 supports both textual and graphical representations of the same underlying model. You do not have to choose between text and diagrams.

Instead, SysML v2 treats text and diagrams as complementary views:

• The textual notation is optimized for precision, completeness, automation, and version control.
• The graphical views are optimized for communication, exploration, and stakeholder engagement.

Modern SysML v2 tools such as SysModeler use the textual notation to automatically generate diagrams in real time. Engineers can write or modify a model in text and immediately view the corresponding diagrams, making it easy to move between detailed modeling and visual communication.

KerML: The Foundation of SysML v2

SysML v2 is not just a revised syntax. Underneath the language sits a new semantic foundation called KerML (Kernel Modeling Language). Unlike SysML v1, which was defined as a UML profile, SysML v2 is built directly on KerML. This provides a formal logical foundation, making your requirements and constraints mathematically rigorous rather than just "annotated boxes". For more info on what KerML is and why it matters see [Lesson 2].

SysML v1 vs. SysML v2: Quick Conceptual Comparison

To make the transition clearer, here is a simplified comparison of familiar SysML v1 concepts and their SysML v2 counterparts:

• SysML v1 Block → SysML v2 part def
• SysML v1 Part Property → SysML v2 part (usage)
• SysML v1 Proxy Port → SysML v2 port
• SysML v1 XMI interchange → SysML v2 standard API and human-readable text

These shifts highlight what SysML v2 is ultimately aiming for. It is not about abandoning diagrams, nor about turning systems engineers into programmers. It is about making system models unambiguous, scalable, and better aligned with modern engineering workflows.