Transitioning from SysML v1 to SysML v2: Textual Notation

At SysGit, we’re very excited about the beta release of SysML v2 and the pending official launch of the next iteration of this powerful and versatile modeling language. Developed over the past several years with input from leading commercial, government and academic organizations, SysML v2 is truly the foundation of the next generation of system modeling. Our team has spent the past few years poring through the SysML v2 specification as we delve into the intricacies of this systems modeling language and implement support for both graphical and textual editing of SysML v2 models into our product SysGit. We’re going to be publishing some of the useful knowledge our team has gained during this process and summarizing some of what we believe will be best practices for your team as they adopt SysML v2 as a modeling language for complex systems. To begin, we’ll start with a very high-level and abstract overview of what we believe will be one of the core enabling differences between modeling in SysML v1 vs. modeling in SysML v2: the textual notation.

SysML v2 Textual Notation

When reading through the SysML v2 specification for the first time (not a task to be undertaken lightly at nearly 700 pages), the most exciting aspect of SysML v2 for our team was and remains the textual notation format. With textual notation, the traditionally graphical modeled language of SysML can also be represented in text — or, for anyone inclined to the world of software engineering, the modeling language can be represented as code. We believe that this ability to represent system models as code provides a paradigm shift for what can be done with the models themselves. Rather than relying on proprietary modeling tools or an export of a model in the XML Metadata Interchange format, a system model can now be represented in a file that can be opened, read and easily understood in any text editor. This also lends to SysML v2 itself being treated as a programming language, where models can be defined and executed similar to how one would write and evaluate code.

The SysML v2 specification provides many examples of textual notation model elements and their corresponding graphical notation representation, but as a quick example of the difference between SysML v1 and SysML v2, we’ll model a requirement in SysML v1, then model the same requirement in SysML v2 graphical and textual notation. This is a very simple example, and does very little to capture the full potential of SysML v1 or SysML v2. But, it does highlight the key differentiator of the textual notation — a new form of representing system models, and the core aspect of SysML v2 underlying our product offering SysGit.

The Potential of Textual Notation

As longtime practitioners of systems engineering can attest, SysML v1 and its associated diagrams have proven invaluable in helping engineering teams model and understand complex systems. However, one of the critical challenges that has faced users of SysML v1 is the limited accessibility of model information when confined to purely graphical representations. While graphical notation has benefits for the visualization and communication of models, it can also be cumbersome to work with, especially for large and highly complex projects. The need to open a specialized tool for every view, or to hunt through multiple diagrams to gather context, can often slow down the modeling process and make it difficult for cross-functional teams to collaborate, especially when other team members may not be familiar with the system modeling tools. Textual notation modeling brings several advantages that we expect will broaden both the adoption and applicability of systems modeling.

The first and most important benefit of the textual notation is the accessibility and clarity of system models. When a system model is stored as textual notation, the access to model information is democratized. Instead of requiring a specialized graphical modeling tool and having additional training in the use of that specific tool, an end-user can use a tool as simple as Windows Notepad, MacOS TextEdit, Visual Studio Code, Vim or Emacs to view the system model. This enables team members that are not system modelers like project managers, engineering subject matter experts or even cost and schedule analysts — to access information stored inside the system models. There’s no complex tool standing between the teams, the stakeholders and the information they need to access. Additionally, the textual notation representation of the system models presents the models in much more human readable format, allowing users — with the help of the SysML v2 specification — to read and understand the system models much more easily than viewing the XML Interchange Format. This lowers the barrier to entry for new team members and stakeholders who need to review or contribute to the model. Because the notation emphasizes readability, it becomes easier to maintain, document, and share over time.

Another significant benefit of textual notation, and as alluded to by our reference to Visual Studio Code, Vim and Emacs, is the familiarity of SysML v2 textual notation to teams who write and maintain software. SysML v2 textual notation is essentially system models written as code. Software developers will feel right at home viewing and editing system models in their text editor or IDE of choice. Moreover, since many engineering groups already manage configuration files and code in version-controlled environments, expressing requirements and system models in a text-based format will feel natural and will allow these teams to seamlessly integrate their requirements and models into existing development pipelines. Integrating this into git via SysGit will also enable more robust and traceable collaboration on the requirements and models, providing deep insights into the evolution of the models and projects over time.

Treating system models as code also affords major benefits for scalability and rapid iteration during development of system models. As system complexity grows, purely graphical models can become unwieldy. Text-based modeling makes it easier to quickly iterate, refactor, and reorganize the model using robust and battle tested software development tooling. For example, if you need to change the name of a model element, a simple find-and-replace operation updates it globally without requiring you to flip through multiple diagrams. More advanced refactoring tools can also be used to refactor entire system models in the textual notation, enabling rapid decomposition or modification of system models.

Finally, SysML v2 has both graphical and textual notation, which allows teams to focus on improving the views for each notation where they specifically excel. Graphical representations still play an essential role when teams need to present a complex system overview to non-technical stakeholders, or when they need to gain high-level insights into a system that may not be possible from the purely textual view. However, with the ability to switch effortlessly between text and diagrams, teams can refine the details of a subsystem in a textual editor, then generate a diagram for broader insights or communication into how these changes impact the model. This flexibility helps teams rapidly iterate on models while ensuring that modeling approaches align with your stakeholder communication.

Agile Engineering with SysML v2

This new notation isn’t just about convenience—it represents a paradigm shift in how we perceive and work with system models, and how we integrate them into the broader hardware engineering enterprise. With SysML v2 textual notation, engineering teams move one step closer to realizing truly agile engineering in hardware development. By describing system models as code, many elements of the traditional systems engineering V-model can now fit neatly into DevOps workflows, enabling rapid, iterative, and agile design and analysis for complex engineering systems.

One of the most immediate benefits of textual notation is that it facilitates collaborative engineering. Because text-based files are straightforward to track in version control systems (like Git, which we’re especially enthusiastic about at SysGit and has been widely adopted across almost all enterprises), multiple users can edit and review changes simultaneously. This approach fosters a more iterative and inclusive modeling culture, encouraging cross-disciplinary input early and often. It also enables branching and merging to be adopted across disciplines. If one team wants to experiment with a new set of parameters or constraints on their model elements, they can branch off from the official working branch and evaluate what sort of first, second and third order effects their changes might have, all while ensuring the baseline design remains intact and in work on the main branch.

Textual notation also encourages reuse and automation. When model elements are defined in a textual format, reusing those elements for different projects becomes far simpler. SysML v2 itself also provides extensive support for the modularization and reuse of model elements, as well as the ability to import, use and redefine elements across the system model. Moreover, scripts and automated tools can parse and manipulate the models programmatically, making advanced validation, testing, and documentation generation much more efficient and less prone to error.

Finally, SysML v2 textual notation enhances agility and integration within modern product development processes. In an environment where continuous integration, continuous delivery (CI/CD), and rapid iteration are standard practice, treating system models ‘as code’ fits naturally with Agile and DevOps workflows. Teams already familiar with checking in and iterating on code multiple times a day can apply the same principles to their system models, speeding up feedback loops and promoting a more adaptive engineering culture.

Textual Notation as the Future?

In short, transitioning from SysML v1 to SysML v2 can open up new possibilities for modeling complex systems efficiently and collaboratively. While graphical views remain invaluable, the textual notation offers a complementary and, in many ways, more powerful approach to expressing and manipulating system data. At SysGit, we’re thrilled to support teams in exploring these new capabilities and to share lessons learned along the way.

Over the coming months, we’ll continue to provide deeper insights into the SysML v2 specification, including best practices for leveraging both graphical and textual notation. We’ll also dive into specific use cases and advanced techniques for integrating SysML v2 into your existing engineering workflows. Stay tuned as we chart this exciting path forward and uncover more ways to streamline systems modeling with SysML v2.