SysML v2 Textual Notation

Overview

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 describes a system as a tree of named elements, written as text. Holarch supports the SysML v2 textual notation, based on the OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI. SysML v2 specification. You write the text in the Editor, and Holarch shows the same elements in the Browser, the views, the tables and the lifecycle pages.

This page teaches the notation with examples from the Hybrid Car (SysML v2) demo. It then lists what Holarch supports, the checks it runs on your text, and the Standard Library.

Concepts

Elements, owners and qualified names

Every element has one owner, except the top-level packages. An element's qualified name is the chain of its owners' names, joined by ::. In the demo, the battery of the powertrain definition is Vehicles::Powertrain::battery.

A name with spaces or other special characters goes in single quotes: 'Fuel Tank'. A short name in angle brackets gives an element a second, short identifier: requirement def <'VR-1'> CurbMass. Holarch uses the short name of a requirement as its number.

Packages

A package groups elements, like a folder. Packages can nest. Each top-level package is one document in the Editor.

package Vehicles {
    doc /* A hybrid passenger car: structure, interfaces and variants. */

    private import ScalarValues::*;
    private import ISQ::*;
    private import SI::*;
}

Imports and visibility

An import makes the members of another package visible by their short names.

• import ISQ::*; imports the members of ISQ.
• import VehicleRequirements::**; also imports the members of nested elements (recursive).
• import Vehicles::Car; imports one element.
• import Vehicles::*[@SysML::PartDefinition]; imports only the members of one kind (a filtered import).

private, protected and public set who else sees a member or an import. The demo writes private import so that imports do not pass on to packages that import it in turn.

Without an import, write the qualified name: ISQ::MassValue resolves anywhere, MassValue only where ISQ is imported.

An alias gives an element a second name: alias Hybrid for Car;.

Definitions and usages

A definition describes a kind of thing. A usage is one use of a definition inside another element. Most keywords come in both forms:

Members nested in a definition belong to every usage of it. part frontAxle : Axle; has the differential, leftWheel and rightWheel of Axle without repeating them.

Typing, specialization and redefinition

Four operators relate definitions and usages. Each has a keyword form too.

Redefinition is how a variant or a configured part changes what it inherits. In the demo, SportCar redefines the spare wheel away:

part def SportCar :> Car {
    attribute topSpeed : SpeedValue = 210 [km/h];
    part redefines spare [0];
}

abstract marks a definition that has no direct instances (abstract part def Component). ref marks a reference that is not owned. in, out and inout set the direction of a feature or parameter. end marks the ends of a connection or interface definition.

Multiplicities

A multiplicity in brackets says how many there are.

• [2]: exactly two. part runabout : CityCar [2];
• [0..1]: optional. part spare : Wheel [0..1];
• [1..*] and [*]: one or more, any number.
• [0]: none, used to remove an inherited part.
• Bounds can be expressions. ordered and nonunique follow the brackets.

Values and units

= binds a value. := gives an initial value that can change. default gives a default that a redefinition can replace.

attribute maxCurbMass : MassValue = 1650 [kg];
attribute minBatteryCapacity : EnergyValue = 1.2 [kW*h];
attribute minPowerToWeight = 40 [W/kg];
attribute topSpeed : SpeedValue = 210 [km/h];

A quantity is a number with a unit in brackets. Units combine with *, / and ^ ([m/s^2]). Quantity kinds such as MassValue come from ISQ, and units such as kg from SI (or USCustomaryUnits). Holarch checks dimensions: assigning 5 [s] to a MassValue is an error.

Expressions use arithmetic, comparison (<=, ==), logical operators (and, or, not, implies), the conditional if c ? a else b, feature chains (car.powertrain.battery.capacity), calls of calculations (PowerToWeight(power, mass)) and sequence operations such as ->sum, ->size, ->select and ->collect. Holarch evaluates them with units for values, constraints, views and analysis pages.

Structure: ports, connections, interfaces, bindings and flows

Parts connect through their ports.

part def Powertrain {
    part tank : FuelTank;
    part engine : Engine;
    interface fuel : FuelLine connect tank.fuelOut to engine.fuelIn;
    connect controller.engineCtl to engine.ecu;
    port output : TorquePort;
    bind output = transmission.output;
}

• connect a to b; joins two parts or ports.
• An interface is a typed connection between ports. Its definition names its ends: interface def FuelLine { end supply : FuelPort; end consumer : ~FuelPort; }.
• bind a = b; says two features are the same (a binding connector).
• flow of Fuel from supply.fuel to produce.fuel; carries an item from one feature to another. message sends an item between parts as an event.

Behavior: actions

An action definition holds its steps (action usages), its parameters and the order of the steps.

action def DriveCycle {
    in attribute targetSpeed : Real;
    first start then switchOn;
    action switchOn { attribute duration : DurationValue = 2 [s]; }
    then fork split;
    then supply;
    then produce;
    action supply : SupplyFuel;
    action produce : ProduceTorque;
    flow of Fuel from supply.fuel to produce.fuel;
    first supply then ready;
    first produce then ready;
    join ready;
}

• Successions order the steps: first a then b;, or then b; right after a. start and done are the beginning and end.
• Control nodes: fork and join for parallel paths; decide and merge for alternatives. A guarded succession after a decision reads if speed > 30 then cruise;, and else brake; is the default branch.
• Other actions: accept waits for a signal, send sends one, assign x := expr; changes a value, if runs a block or skips it, while … { … } until …; and for v in seq { … } repeat a block.
• Allocation of behavior: a part performs an action (perform action trip : DriveCycle;, perform trip.supply;), and allocate a to b; allocates one element to another.

Behavior: states

A state definition holds states and the transitions between them.

state def PowertrainStates {
    entry; then off;
    state off;
    accept StartRequest then hybrid;
    state hybrid {
        entry action startEngine;
        do action driveHybrid;
        exit action stopEngine;
    }
    transition recharged first hybrid if charge > 60 then electric;
}

• entry; then off; sets the initial state.
• Transitions have a trigger (accept StartRequest), an optional guard (if charge > 20) and an optional effect (do …). The short form follows the source state; the long form is transition name first a … then b;.
• entry, do and exit actions run on entering, while in, and on leaving the state. parallel states have regions that are all active at once.
• A part exhibits a state: exhibit state powertrainStates : PowertrainStates;.

Requirements, constraints and verification

A requirement holds its statement in doc, the element it applies to as subject, and a checkable condition as require constraint.

requirement def <'VR-1'> CurbMass {
    doc /* The car's curb mass shall not exceed the mass limit. */
    subject car : Car;
    attribute limit : MassValue;
    require constraint { car.curbMass <= limit }
}

satisfy carSpec by fleet.sedan;

• assume constraint states a condition the requirement assumes. actor, stakeholder and frame concern name who and what the requirement is for.
• satisfy R by part; says a part meets a requirement.
• A verification case verifies requirements in its objective: objective { verify carSpec.sedanMass; }. It can return verdict : Boolean = …;.
• An analysis case has a subject, an objective and a return result that Holarch evaluates when every input has a value.
• connection : Derivation connect original to derived; records a derived requirement. #refinement dependency x to R; records a refinement.
• dependency from a to b; records a general trace.

Use cases

use case def DriveToWork { subject car : Car; actor driver : Driver; objective { … } include use case startCar : StartCar; }. A use case usage takes its definition's subject and actors.

Views

A view shows part of the model. It is typed by a standard view definition and exposes what it shows:

view driveCycleFlow : StandardViewDefinitions::ActionFlowView {
    expose DriveCycle;
}

filter narrows the elements (filter @SysML::RequirementUsage;). render chooses a rendering. A viewpoint frames the concerns a view must address. SysML v2 Views explains each view kind.

Comments, documentation and metadata

• doc /* text */ documents its owner. It is part of the model; for a requirement it is the requirement text.
• comment about x /* text */ is a note in the model about another element.
• // text and //* text */ are notes in the text only. Holarch keeps them in the text but they are not model elements.
• Metadata annotates an element: @TBD { owner = "Powertrain lead"; } in a body, #TBR attribute limit … as a prefix, or metadata Capability about Vehicles::Car; from outside.

Holarch's own discussion comments, labels, assignees and due dates are kept next to the model. They are not written into the text.

How to use it

Model a structure

1. In the Editor, open a package (or click + New Package).
2. Write a port def for each kind of connection point, with directed features (out attribute torque : TorqueValue;).
3. Write a part def for each kind of component, with its attributes and ports.
4. Write a part def for the assembly, with a part for each component.
5. Connect the parts: connect a.p to b.q;, or interface name : Def connect a.p to b.q;.
6. Pause. The status line says Applied and the Browser shows the new elements.

Insert ▾ (or ⌃⇧Space / Ctrl+Shift+Space) writes each of these constructs for you, with fields to fill in. See Insert a construct.

Give values with units

1. Import the quantity kinds and units at the top of the package: private import ISQ::*; and private import SI::*;.
2. Type the attribute by a quantity kind and give a value: attribute mass : MassValue = 45 [kg];.
3. In a definition that inherits the attribute, redefine it with its own value: attribute redefines mass = 18 [kg];.
4. Point at the value. An error card appears if the unit does not fit the quantity kind.

Describe behavior

1. Write an action def with its in and out parameters.
2. Add a step per action usage and order them with first … then …; or then.
3. Use fork and join for parallel steps, decide and merge for alternatives.
4. Add flow of Item from a.out to b.in; between the steps that pass items.
5. In the part that carries out the behavior, write perform action name : Def; and, in its parts, perform name.step;.
6. Open the action in an Action Flow View to see it drawn (see SysML v2 Views).

Write a requirement and trace it

1. Write requirement <'ID'> name { doc /* The system shall … */ subject s : Def; }.
2. Add require constraint { … } when the requirement can be checked against values.
3. Write satisfy name by somePart; where the design meets it.
4. Write a verification whose objective verifys it.
5. Open Needs & Requirements → Requirements: the requirement is listed with its number, and Verification → RVTMRequirements Verification Traceability Matrix A table of each requirement with how it is verified, the tests that verify it and their latest result. shows how it is verified. See Requirements and Verification in SysML v2 Projects.

Mark a value as TBD or TBR

Writing TBD in place of a value is not valid SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.. Use Holarch's metadata instead.

1. Import it: private import HolarchMetadata::*;.
2. Prefix the attribute: #TBD attribute chargerPower : PowerValue; (no value yet) or #TBR attribute limit : TimeValue = 0.5 [h]; (a value to review).
3. To record an owner and reason, write the long form in the attribute's body: @TBD { owner = "Powertrain lead"; rationale = "The charging standard is not chosen yet."; due = "2026-12-01"; }.

The TBDTo Be Determined A requirement value or detail that is not known yet. Holarch tracks TBDs with an owner and a due date./TBRTo Be Reviewed A requirement value that is filled in but still needs to be confirmed. register lists these values. TBD and TBR specialize ModelingMetadata::StatusInfo, so other SysML v2 tools read them as status annotations. Insert ▾ → TBD Value and TBR Value write them for you.

Find a library name

1. Open Standard Library from the rail tools.
2. Type part of the name in Find a package or definition…, for example MassValue.
3. Click Copy Name on the row. The qualified name, here ISQBase::MassValue, is copied.
4. Paste it in the Editor, or import its package and use the short name.

Worked example: read the sedan's requirement

This example follows one requirement through the Hybrid Car demo text.

1. Open the demo and choose VehicleRequirements in the Editor's Packages list.
2. Find requirement def <'VR-1'> CurbMass. Its require constraint { car.curbMass <= limit } compares the subject's curb mass to limit.
3. Find requirement carSpec. It holds requirement <'VR-1.1'> sedanMass : CurbMass { attribute :>> limit = maxCurbMass; }. The usage redefines limit with the package-level target maxCurbMass = 1650 [kg].
4. Find satisfy carSpec by fleet.sedan;. ⌘ / Ctrl-click sedan: the Editor opens Vehicles at part sedan : Car, where attribute redefines curbMass = 1580 [kg]; gives the value.
5. Back in VehicleRequirements, find verification def CurbMassTest. Its objective verify carSpec.sedanMass; makes it a verification case of VR-1.1, and verification sedanWeighing : CurbMassTest { subject car = fleet.sedan; } applies it to the sedan.
6. Change 1580 [kg] to 1700 [kg] in Vehicles and pause. The sedan now exceeds the 1650 kg limit, and the Editor shows a warning in VehicleRequirements that the requirement is not met by sedan, with the false constraint and its values. Undo with ⌘Z / Ctrl+Z.

Tips and common mistakes

• “…” is not defined here. The name is misspelled or its package is not imported. Add private import Package::*;, or write the qualified name.
• A missing ;. Each declaration ends with ; or a { … } body. The declaration does not end. Add ; or a { … } body.
• :> versus :>>. Use :> to specialize or subset; use :>> to replace an inherited feature. Redefining a feature that is not inherited gives “x” is not inherited by “y”.
• Units need imports. 5 [kg] resolves only where SI is visible.
• Two members with one name. “x” is already used in this namespace. Rename one; a variant redefines instead.
• verify outside an objective. Put it in objective { verify R; } of a verification case.
• Keywords as names. Words such as part, state or action are reserved. Quote them ('state') or choose another name.

What Holarch supports

Holarch supports the following parts of the SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 textual notation. The Editor checks all of them, and the model keeps them.

Kept as written, not interpreted

Holarch reads and keeps these constructs exactly as written, but gives them no meaning of its own:

• variation and variant (variant selection and configurations);
• individual, snapshot and timeslice (individuals and time slices);
• user-defined metadata definitions, apart from the Holarch packages above;
• textual representations (rep … language).

Not yet available

• Running state machines in the Simulator (action flows run).
• Importing KerML files (.kerml).
• Writing to Holarch through the Systems Modeling API: other tools read the current model only (see The API and MCP in SysML v2 Projects).
• User-defined keywords and other language extensions.

Checks

Holarch checks the text as you type. Each problem is marked in the Editor's gutter and underlined; the message states the problem, then the fix. Errors stop a member from being applied; warnings do not.

The Standard Library

The Standard Library page lists the packages and definitions every SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project can use: values and units, quantities, parts, ports, actions, states, requirements, analysis and more. It is read-only.

• Open it from Standard Library in the rail tools. In LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects this place holds the Schema.
• Folders. The left side lists the library files by folder: Kernel Libraries, Systems Library, Domain Libraries (Analysis, Cause and Effect, Geometry, Metadata, Quantities and Units, Requirement Derivation) and Holarch (the HolarchMetadata package with TBDTo Be Determined A requirement value or detail that is not known yet. Holarch tracks TBDs with an owner and a due date. and TBRTo Be Reviewed A requirement value that is filled in but still needs to be confirmed.).
• A file. Select a file to see its packages, each with its documentation and a table of its definitions: Name, Kind and Documentation.
• Find. Type in Find a package or definition… to search the names and documentation of every file. Results show the file; click it to open that file. Press Esc to clear.
• Copy Name copies an element's qualified name, such as ISQ::MassValue, to use in the Editor.
• Show Text shows the library file as written; Show Definitions returns to the tables.

The library is the SysML v2 release library, unmodified. Your model refers to it by name; it is not copied into the project, and it is not part of a .sysml export.

Limits

• A text document larger than 8 MB is not checked: This text is larger than 8 MB and is not checked. Split it into several packages.
• A line longer than 64 KB is not checked.
• Nesting deeper than 256 levels is not checked.
• The standard library cannot be edited, and user-defined keywords are not available.

Related pages

• Getting Started with SysML v2 Projects
• The Text Editor and Browser
• SysML v2 Views
• Requirements and Verification in SysML v2 Projects
• Exchanging SysML v2 Models

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.® and OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI.® are registered trademarks of Object Management Group, Inc. in the United States and other countries.