Why Textual SysML v2

SysML v2 is a language for describing systems – what they are made of, how they behave, and what they must do. You write it as plain text, the same way you write code.

Here is a complete SysML v2 model:

package CoffeeMachine {
    part def Grinder;
    part def Brewer;
    part def CoffeeMachine {
        part grinder : Grinder;
        part brewer : Brewer;
    }
}

Read it as: a CoffeeMachine contains a Grinder and a Brewer. It is not a diagram, and it is not a database. It is text in a file, and that file is the model.

Definition and usage: the idea everything else rests on

Look again at those seven lines. Grinder appears twice, and the two appearances mean different things.

part def Grinder introduces a definition – the kind of thing a grinder is. There is one of these no matter how many grinders exist.

part grinder : Grinder introduces a usage – one particular grinder, in the context of this coffee machine, typed by that definition.

If you have written code, the instinct is to read this as class and instance. It is close enough to get started, and Chapter 3 will sharpen it. What matters now is that the split is not a convention someone adopted – it is built into the language. The specification gives definitions and usages their own clause of the textual notation (SysML §8.2.2.6), and nearly every construct you will meet comes in both forms: action def and action, state def and state, requirement def and requirement.

Learn to ask “is this a kind, or a particular one?” and a large part of SysML v2 stops being a vocabulary problem.

Why text

When your model is a text file, you inherit the tooling you already have:

• Diff and review. A change shows up as a line-by-line diff. A reviewer can comment on the exact line where a requirement changed or a port was renamed.
• Version control. Branch, merge, and tag model versions the way you tag releases. The model’s history is the repository’s history.
• Automation. A pipeline can parse the model, check its constraints, and fail the build before anyone sits down to a review meeting.

None of that is available when the model lives in a proprietary binary, and none of it needs a special tool beyond the ones you already run.

What the specification actually says about notation

It would be convenient to claim text is the one true form of a SysML v2 model. That is not what the standard says, and the real answer is more useful.

SysML v2 defines two concrete notations: a textual notation (§8.2.2) and a graphical one (§8.2.3). Both are normative. A tool can demonstrate Textual Notation Conformance, Graphical Notation Conformance, or both – and a tool claiming the graphical variant must support the textual notation at least far enough to render text inside diagrams correctly (SysML §2).

Underneath both sits the abstract syntax: the metamodel of elements and relationships that a model really consists of. Notation is how you write it down. This is why diagrams and text are not rivals. They are two projections of one model, which is also why a diagram can be generated from text but a well-formed model cannot be recovered from a picture alone.

Two conformance levels are mandatory for every conformant tool: Abstract Syntax Conformance and Model Interchange Conformance. Notation support is optional (SysML §2). So a tool is allowed to read and write SysML v2 models without offering either notation – which tells you where the standard thinks the model lives.

Interchange is specified too: projects travel as a .kpar archive, and textual files inside it use the .sysml extension. Those extensions are normative, not conventions.

Where SysML v2 came from

SysML v1 was a profile of UML – a set of stereotypes layered onto a general-purpose software modeling language. SysML v2 is not. It is a metamodel that extends the Kernel Modeling Language (KerML), a domain-independent language for building semantically rich modeling languages (SysML §1).

Two consequences you will feel while reading this book:

• Names from KerML surface constantly. Occurrence, Feature, Classifier, Specialization are KerML’s, not SysML’s. When a chapter cites a KerML clause, that is why.
• The standard library is part of the language. Types like Real, String and the ISQ units are defined in model libraries that ship with the specification (Clause 9), not baked into the grammar.

The standard also specifies a formal transformation from SysML v1.7 to v2, so migration is a defined activity rather than a rewrite from scratch. That is Appendix B.

What this book builds

Sixteen chapters that grow one model – a smart coffee machine – from an empty file into a complete specification:

• Chapters 2–5 build the structure: definitions and usages, packages, parts, ports, attributes.
• Chapters 6–8 add behaviour: connections and interfaces, actions with control flow, states with guarded transitions.
• Chapters 9–10 make it checkable: expressions, constraints, requirements and verification cases.
• Chapter 11 assembles the whole thing into one coherent model.
• Chapters 12–14 go deeper: specialization and redefinition, metadata and views, libraries.
• Chapters 15–16 are about working with a model: projects and workspaces, and what it means to run one.

Then ten appendices of reference material – syntax, migration, the API, tooling notes, physics-aware simulation, diagnostic codes, relationship kinds, lexical rules, review checklists, and occurrences, time slices, and snapshots.

How to read it

Start at Chapter 2 and work forward; each chapter builds on the one before, and the model assumes you have the earlier chapters. If you already model in SysML v2, jump to what you need and follow the back-references.

Where a claim about the language is load-bearing, the text cites the clause so you can check it. Where something is a particular tool’s behaviour rather than the language’s, it says so – usually in a note like the ones you will meet in Chapter 8 – so you can skip those and still learn SysML v2.

Blocks marked sysml are real model text, and every one of them is checked against a parser before this book ships. Most are complete enough to drop into a .sysml file as they stand; some are fragments of a larger model, and a few use ... to elide a part you have already seen. Blocks marked text are syntax templates with <angle> placeholders – shapes to read, not code to run.

You do not need the tool to follow along, but if you want it, Appendix D explains how to get it.

Here is that same coffee machine as a diagram – the same model, the other notation: