The SysML v2 Book

A practical, example-first guide to textual SysML v2, in the spirit of The Rust Programming Language.

SysML v2 has a textual notation, and it is the part of the language most approachable to anyone who already writes code: you can put a model in version control, review it in a pull request, and check it with a tool. This book teaches that notation from the first part def to a complete, executable system model.

The book is the language half of a documentation pair: the sysml-rs documentation portal documents the sysml-rs tool itself, and also serves this book under its Learn section.

Status: pre-1.0 and incomplete. Chapters are being verified against the specification and revised. Expect gaps and rough edges, and please report anything that is wrong.

What is in here

Sixteen chapters that build one model incrementally -- a smart coffee machine, with a grinder, a brewer, a water tank and a control panel -- from definitions and usages through structure, connections, actions, states, expressions and constraints, requirements and verification, up to running the model.

Then ten appendices for reference: a syntax quick reference, a SysML v1 migration guide, the Systems Modeling API, tooling notes, the physics-aware simulation reference, diagnostic codes, a relationship and element kind reference, a lexical reference, modeling review checklists, and a guide to occurrences, time slices, and snapshots.

After the appendices, a generated Language Reference section (src/language-reference/) indexes every SysML v2 / KerML language concept with its normative clause citations, examples, and measured tool support, and the underlying machine-readable card JSON ships with the built book under language-pack/ for tools and agents. Both are rendered from the sysml-rs language pack by ./tools/render-language-pack.sh.

src/SUMMARY.md is the table of contents and the single source of truth for what is in the book.

The specification is the authority

The book teaches the language as the OMG SysML v2 and KerML specifications define it, and cites clauses where a claim is load-bearing so you can check it. Where it describes something a tool does rather than something the language says, that is called out separately -- usually in a blockquote -- so you can skip it and still learn the language.

Examples are checked with a maintainer-run tool rather than written from memory. tools/check-code-blocks.py extracts every sysml code block in the book and parse-checks it against a real parser:

SYSML_BIN=/path/to/sysml python3 tools/check-code-blocks.py

It reports blocks that fail to parse in any valid context. It needs a built sysml binary from sysml-rs. The check is not yet enforced in this repository's CI: sysml-rs releases do not currently publish the sysml CLI as a prebuilt binary, and generating the parser from source is too slow for the book's build workflow, so the check runs on a maintainer's machine before publishing.

Repository layout

• src/ -- chapter sources. src/SUMMARY.md is the table of contents
• src/viewer/ -- committed standalone renderer bundle and baked ViewModel fixtures
• examples/ -- three runnable example projects, 28 model files. The running coffee machine is examples/coffee-machine/ (15 files)
• tools/ -- the code-sample checker and diagram-baking scripts
• book.toml -- mdBook configuration

Building

Needs mdBook and the tabs preprocessor:

cargo install mdbook mdbook-tabs
mdbook build     # output in _book/
mdbook serve     # preview at http://localhost:3000

create-missing is off, so a table-of-contents entry pointing at a file that does not exist fails the build rather than quietly generating an empty page.

Refreshing embedded diagrams

The book ships a static copy of the current sysml-rs SVG renderer and pruned ViewModel JSON for its declared coffee-machine views. This keeps GitHub Pages self-contained; readers do not need a server running behind an embed. With a sibling sysml-rs checkout, rebuild both the bundle and fixtures with:

./tools/build-viewer.sh

The script uses sysml export viewmodel, checks every baked JSON payload has the ViewModel schema, and writes the committed src/viewer/ output. Set SYSML_BIN=/path/to/sysml to use a prebuilt CLI instead of cargo run.

Contributing

Corrections are the most useful contribution, particularly anywhere the book states something the specification does not support. If you are reporting a problem with an example, please include the output of sysml check on it.

Licence

The prose is CC-BY-4.0. The code samples and everything under examples/ are MIT OR Apache-2.0, the same terms as the tool, so you can lift a snippet into your own model without inheriting an attribution obligation. See LICENSE.